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Preface 

This book is a follow-up to Radio Shack's book TRS-80 
Assembly-Language Programming. In that book we 
described the architecture of the Z-80 microprocessor used in 
the TRS-80, presented the instruction set and addressing 
modes, and gave some examples of common 
assembly-language programming operations. 

More TRS-80 Assembly-Language Programming builds on 
the material found in the previous book by taking an even 
more practical look at TRS-80 Model I and III 
assembly-language programming. It answers such 
questions as "How do I use the Disk Editor/Assembler?," 
"Where in memory should I put an assembly-language 
program?," "What about embedded machine-language 
code?" and "How do I go about writing and implementing a 
large assembly-language program?" 

We have organized the material in this book into four 
sections. In the first section, "Using Assembly Language," 
we review some of the general material we covered in the 
earlier book and then describe the practicalities of 
assembling programs in the TRS-80. Among the 
practicalities we discuss are the operation of both the 
cassette-based Editor/Assembler and Disk Editor/Assem- 
bler. Moving along, we get into the general approaches to 
executing assembly-language programs, both "stand-alone" 
assembly-language programs and the "embedded in BASIC" 
machine-language approach. 

Section II, "Assembly-Language Techniques," describes 
four types of processing that can be implemented in 
assembly language — "number-crunching;" working with 
character data; table operations, including sorting and 
searching; and graphics display processing. We present each 
type of processing first from a general design standpoint — 
and then we put that theory into practice, with assembly- 
language code to illustrate the methods of solving the 
problems of each type of processing. 



Because of the unique structure and design of the TRS-80 
hardware there are a number of assembly language 
techniques that are peculiar to this system. Along that line, 
we take two more chapters in this section to describe cassette 
input/output, parallel printer operation, and disk file 
manage operations. Some of you may be especially 
interested in the material on disk file operations since 
assembly-language calls may be made directly to TRSDOS 
disk file manage routines to read and write random files and 
perform other operations. 

The third section, "Larger Assembly-Language Projects," 
contains complete listings of two large assembly-language 
programs. The first of these is a Morse Code Program 
(MORG), which transmits random or defined Morse code 
messages through the cassette output port at speeds of 5 to 
60 words per minute. The second program is an experiment 
in artificial intelligence — a tic-tac-toe learning program 
that starts off being not very bright but learns how to play 
the game until it is virtually unbeatable. Neither program 
could be implemented in BASIC to execute in "real-time." 
Also in this section we discuss the general approach m 
writing large programs in assembly-language along with an 
actual case study from a TRS-80 software house. 

The fourth and final section contains the appendices 
covering the Z-80 instruction set grouped in functional order 
and Z-80 operation code listings. 

As the author, I hope you find the material in this book a 
useful supplement to TRS-80 Assembly -Language Pro- 
gramming, but I also hope you will be able to use it in its own 
right. Assembly-language programs are fast, efficient, and 
challenging, and help to make the TRS-80 even more of a 
valuable tool for all types of programming applications. 



To my wife Janet, for her encouragement 
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SECTION I 

Using Assembly Language 

Chapter One 
Assembly-Language Basics 



In this chapter we'll review some assembly-language 
basics. If you want a more comprehensive treatment, refer 
to TRS-80 Assembly-Language Programming (Radio 
Shack 62-2006). If you've never experimented with 
assembly language, review some of the material presented 
in the previous book (especially the "General Concepts" 
section). An alternative is to read this chapter thoroughly 
and pay close attention to assembly-language examples 
we've included later in the book. 



By the way, when we use the term "TRS-80" in this 
book we'll be referring to both the Model I and III. 
There are some minimal differences between the two 
systems (which we'll note) but in general, material in 
this book applies to either system. 



The TRS-80 uses the built-in instruction set of the Z-80A 
microprocessor. The Z-80A is a third-generation micro- 
processor chip that is truly a "computer on a chip." Using 
assembly language is mainly a matter of learning both the 
instruction set of the Z-80A microprocessor and the skills 
needed in putting together those instructions to form 
programs. 

There are over 700 separate instructions for the Z-80 with 
a number of different addressing modes. Each of the 
instructions, however, performs a simple function and is 



easy to understand by itself. Furthermore, many of the 
instructions are similar in nature, and understanding how 
one specific instruction works might mean that you can 
easily unravel 23 similar ones! 

The instruction set of the Z-80 is provided in Appendix I 
with the instructions grouped according to logical 
function. If you want to find an instruction that will load 
the A register in the Z-80 with a memory operand, for 
example, you could look under "Loads" and then under "A 
Load Memory Operand" to find the instructions that 
perform this function. Many times you'll find a number of 
different instructions can accomplish the same function. 

Appendix II gives the actual format of each instruction. 
Normally, you will not be concerned with the format, as 
the Assembler will automatically translate a mnemonic 
for the instruction into the machine-language format. 

It's possible to translate a string of assembly-language 
instructions by hand into the equivalent bits shown in the 
instruction formats of Appendix II. If you did this, the 
result would be called a machine-language program. 
However, there are a number of excellent automatic 
assembler programs that Radio Shack provides that 
eliminate such tedious hand work. One of these is the 
cassette-based Editor/Assembler which takes symbolic 
source lines and translates them into machine-language 
code. The second is the disk-based Editor/Assembler, a 
more advanced version of an assembler. We'll look at both 
assemblers in this book and point out any differences that 
occur between them. 

A Typical Assembly Program 

One listing is said to be worth a thousand words . . . Let's 
take a look at a typical assembly-language program and 
scrutinize it in some detail to review some of the things we 
should know before we go on to advanced topics. 

The assembly-program listing is shown in Figure 1-1. The 
program itself is designed to convert a character string 
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representing a decimal value of 0-65535 into an equivalent 
16-bit binary value. This program could be used, for 
example, to convert a keyboard input to binary for 
processing. 



8590 
8591 
8592 
8591 
8598 
859A 
859C 
859E 
85AO 
85A1 
85A3 
85 Ail 
85A6 
85A9 
85AB 
85AE 
85AF 
85B1 
85B3 
85 BH 
85 B6 
85B7 
85B8 
85BA 
85BB 
85 BD 
85BE 
85BF 



C5 

D5 

DDE5 

DD210000 

DD29 

DDE5 

DD29 

DD29 

D1 

DD19 

7E 

D630 

FAB685 

FEOA 

F2B685 

5F 

1600 

DD19 

23 

10E2 

78 

B7 

DDE5 

E1 

DDE1 

D1 

CI 

C9 



08970 
08980 
08990 
09000 
09010 
09020 
09030 
09040 
09050 
09060 
09070 
09080 
09090 
09100 
09110 
09120 
09130 
09110 
09150 
09160 
09170 
09180 
09190 
09200 
09210 
09220 
09230 
09240 
09250 
09260 
09270 
09280 
09290 
09300 
09310 
09320 
09330 



""""DECIMAL 10 BINARY CONVERSION SUBROUTINE""""" 

• CONVERTS HP TO SIX ASCII CHARACTERS REPRESENTING « 

• DECIMAL NUMBER TO BINARY. MAXIMUM VALUE IS 65535. ' 
' ENTRY: (HL)=BUFFER CONTAINING ASCII « 
" (B)=NUMBER OF CHARACTERS • 
« EXIT: (HL)=BINARY t 0-65535 • 
8 NZ IF INVALID ASCII CHARACTER OTHERWISE Z » 

• ALL REGISTERS SAVED EXCEPT A,HL » 



DECBIN 



DEC070 



PUSH 

PUSH 

PUSH 

LD 

ADD 

PUSH 

ADD 

ADD 

POP 

ADD 

LD 

SUB 

JP 

CP 

JP 

LD 

LD 

ADD 

INC 

DJNZ 

LD 

OR 

PUSH 

POP 

POP 

POP 

POP 

RET 



BC 

DE 

IX 

IX, 

IX, IX 

IX 

IX, IX 

IX, IX 

DE 

IX, DE 

A,(HL) 

30H 

M.DEC070 

10 

P.DEC070 

E,A 

D,0 

IX, DE 

HL 

DEC040 

A,B 

A 

IX 

HL 

IX 

DE 

BC 



iSAVE REGISTERS 



iSET RESULT 

;INTEHMEDIATE«2 



•2 

•10 

GET CHARACTER 

CONVERT 

GO IF LT "0" 

TEST FOR GT «9" 

GO IF GT "9" 

NOW IN E 

NOW IN DE 

MERGE 



;GO IF MORE 
; COUNT TO A 
iSET OR RESET Z FLAG 
;RESULT TO HL 

IRESTORE REGISTERS 



Figure 1-1. Typical Assembly-Language Program 



This collection of assembly-language statements makes up 
a subroutine, a structure very similar to a BASIC sub- 
routine. It is located at one place in memory and can be 
called as often as necessary. 

There are three main segments of the assembly-language 
program: the assembly-language source code, the edit 
line numbers and the assembly-language machine code. 

Figure 1-2 shows the assembly-language source code 
portion of the listing. The source code consists of symbolic 
lines similar to BASIC statement lines. In general, each 
line represents one assembly-language instruction written 
in mnemonic form. The mnemonic of the instruction is 
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merely a shorthand way to express the instruction. It's 
much simpler to write DEC DE than to write "take the 
contents of the DE register, subtract one, and put the 
results of the operation back into DE". 









LABEL 


OP-CODE 
















FIELO 


FIELD 


OPERAND FIELD 


COMMENTS FIELD 






'I,.:i7(' 


lill-tt 


"DECIMAL 


TO BINAR5 


CONVERSION SUBROUTINE*-""- •« 






<<*•■• nn 


» COHVEBTS UF 


TO SIX ASCII CHARACTERS REPRESENTING 






OS '.<■?'.! 


» DECIMAL NUMBER TO BINARY. MAXIMUM VALUE IS 65535. " 






■? u :.' 


» ENTRY; (HL) 


=BUFFER CONTAINING ASCII 






CiOOlC 


fi 


(B) = 


NUMBER OF 


CHARACTERS 






■': :• 


« EXIT: (HL) 


-BINARY 1 


0-65535 






i -iij .'.■■ 


- 


NZ IF INVALID 


ASCII 


CHARACTER OTHERWISE Z 






I'liuo 


« ALL 


REGISTERS SAVED 


;xcept 


S,HL 






O'VOil! 












;■". '.)0 


05 


"> IJI.U 


>ECBIH 


PUSH 


BC 




SAVE REGISTERS 


."■■:. '<? 


D5 


.vji',7i. 




PUSH 


DE 






■:■'.':- 


:>[. l', 


(.•Ji'i !■..-■ 




PUSH 


IX 






i'.-,'.)ll 


r.f'j i oci-. ■■ 


u'liiv 




LD 


IX. 




.SET RESULT 


Or. -'.if. 


:, |,...(, 


O'l 1 Od 


DEC010 


ADD 


IX. IX 




; INTERMEDIATED 


o-.-i; 


r-n -:•_- 


01 1 1'"' 




PUSH 


IX 






859C 


DD29 


09120 




ADD 


IX, IX 






«n 


859E 


l.'Ul") 


O'll ?..'> 




ADD 


IX, IX 






fl 8 


85 AO 


D1 


O'i l-'iO 




POP 


DE 






-2 


.:. s ,'•. l 


i r.'iv 


u ■■ ; v. o 




ADD 


IX, DE 






•10 


7 -' .■'. ■ 


7E 


'■■-.' 1 t.u 




LD 


A, (HL) 






GET CHARACTER 


85 All 


i'i. :,u 


U'-IVu 




SUB 


30H 






CONVERT 


!'. '-. A t. 


I i . bdUO 


■■)■'! 1 !.U 




JP 


H.DEC070 






GO IF LT "0" 


i '.>..■ i 


:-::u ,-, 


O'I 1'IU 




CP 


10 






TEST FOR GT "9" 


Sf .\i'. 


!-.■!'.'■. r.-. 


i'l-Sii 




JP 


P.DEC070 






GO IF GT "9" 


C . ,U 


51' 

1 u 


iV.K'K' 

i'.-:.';o 




LD 
LD 


E, A 
D,0 






NOW IN E 
NOW IN DE 


■:- r , L'-l 


M'liv 


o«:-jo 




ADD 


IX, DE 






MERGE 


;-Mi~: 


23 


i'i9J.'ni 




INC 


HL 






85BM 


io:.- 


u -J a r= o 




DJNZ 


DECMO 




;GO IF MORE 


oMi. 


76 


i'i*) i-iiy 


DEC070 


LD 


A.B 




; COUNT TO A 


;;■: U7 


1>7 


iitOY'J 




OR 


A 




;SET OH RESET Z FLAG 


SiNlSV 


im 


09 28 




PUSH 


IX 




; RESULT TO HL 


f>')Ei', 


E1 


u'V-"H! 




POP 


HL 






ilM-.Ii 


DDE1- 


0'. -,00 




POP 


IX 




;HEST0RE REGISTERS 


!'.-. L.[. 


'M'fivPV* 


O-'iSIO 




POP 


DE 






85BE 


' c1;'' ; f j3 ; ' : 


'!') :■-'■' 




POP 


BC 






85I5F 


C9 


09330 




RET 






; RETURN 



Figure 1-2. Source Code 

There are four fields in each assembly-language source 
line. 

The second field is the mnemonic representing the 
instruction to be used. Each of the 700 or so instructions 
has a predefined mnemonic that the assembler recognizes 
as a valid instruction. As the mnemonic defines an oper- 
ation code for the instruction, this field is often referred 
to as the op-code field. 

The third field in the source line is the operand field. The 
number of operands for instructions varies from none to 
three. The RET instruction shown in the figure, for 
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example, requires no operands, while one of the LD 
instructions requires two — one specifying the register 
pair that points to a memory address -C ( HL ) >, and a 
second specifying the register to be loaded with the 
contents of that memory address ( A ) , The complete 
op-code and operand form of the instruction is 
LD A »(HL) . 

The fourth field of the instruction is an optional com- 
ments field. This field is used solely for comments as- 
sociated with the instruction, similar to the "REMarks" 
statement of BASIC. A source line is a comment line when 
the line starts with a semicolon (;). The comments field 
must always start with a semicolon. 

The remaining field of the source line is the optional label 
field. We use this field to define a label for the instruction, 
which can then be referenced by another instruction in the 
program. The line D ECO 40 ADD IX , IX, for example, has 
the label DEC0 40 for the ADD instruction. A later 
instruction, DJNZ D ECO 4 0, causes a jump to DEC040 if 
there is a zero result in the B register. The use of symbolic 
names for instruction locations makes it unnecessary to 
keep track of the absolute locations for each instruction in 
memory. Keeping track of absolute locations is a 
burdensome chore, although it can be done in 
machine-language programming, which does not use an 
assembler. The label may or may not be suffixed by a 
colon, depending upon the assembler. 

The second part of the assembly listing, shown in Figure 
1-3, is the editing of line numbers. The source code lines 
are entered from the keyboard to an editor program, 
which is usually part of an Editor/Assembler package. The 
Editor uses line numbers for each of the source lines with 
the line numbers in ascending sequence. The typical line 
number increment is 10, so that the line numbers are 100, 
110, 120, etc. Using the Editor, lines may be modified, 
inserted, or deleted. Characters within the lines may also 
be processed. 
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6 r . *K' 
("if 
8592 
8591 
S«6 
&v?;. 
859C 
859E 
85 AO 
(5.SA1 

85*3 

6 5 .Ml 
65 A6 
85 A9 

SSAB 
65 AE 
85AF 

e?Bi 

85B3 

J5B-'. 

i-soi;. 

85156 
85BA 
85BB 
85BD 
85BE 
85BF 



C5 
D5 
DDE5 

[.;>:' •. uooo 
t' i' : ? 

DDES 
DD29 
DD29 
Dl 

r ■ d i •". 

7E 

'.if. 30 

FAB6B5 

TEOA 

F2B685 

5F 

1600 

DD19 

23 

10E2 

■'. 

B7 

i!!'C5 

El 

DDE1 

D1 

CI 

C9 



08970; 
089805 
08990 p 
09000; 
09010! 
09020! 
09030; 
090U0I 
09050 5 
09060 | 
09070 ; 
09080 ; 
090901 
09100! 
091 10 ! 

09120 

09130 

09110 I 

09150 

09160 

09170 

09180 

09190 

09200 

09210 

09220 

09230 

09210 

09250 

09260 

09270 

09280 

09290 

09300 

09310 

09320 

09330 



msooaoDECIKAL TO BINARY CONVERSION SUB1I0UTIN El* 5 ™ ■ » 

1 ro:iv;:riT:' ui 10 .5;;; .'.jcii a:.\:i.-,c-: Li.:- iil-p;- l.-.-t ::t ■ :. >j 
' iilciiml ■niiiL r. r; -:o :■::..•,»(. i;a>. ;::'JM vai.u:' ;;• {.■'■■•!'.■■ 

1 ENTRY: ( HL) = BUFFER CONTAINING ASCII 

(B)=1!UMBER OF CHARACTERS 
> EXIT: C1IL) = BI1IARY ii 0-65535 
i ::: i; ; : v ,-. l i [.■ ;..■'.■ ii rn;.::A'""ri. iiTi:i:ii» ic-F. r. 

i ALL REGISTERS SAVED EXCEPT A, ML 



PUSH 

PUSH 

PUSH 

LD 

ADD 

PUSH 

ADD 

ADD 

POI 

ADD 

LD 

SUB 

JP 

CP 

JP 

LD 

LD 

ADD 

:■. 

DJKZ 

•:;ld ' : 

UR 

pith 

I' Or 

POP 

FOP 
POP 
RET 



BC 
: !.■£ 
IX 
' " . ■ 

IX, IX 

IX 
IX, IX 

i :•: , i x 

DF. 

: x , n t 
;,(i;d 

30H 

::, i-Lccivc 
10 

P.DEC07 
E, A 

it . 

i x , : i :: 

[1L 

['ICCiilO 
A,B 

:x 

HL 
IX 
DE 
DC 



i ;■. a v r iE'i; 






;SET RESULT 

; INTERMEDIATE' 



; =10 

;GE? aiAS..U'"£!< 
; COW FAT 
j C ! F L f " u " 
;TEST FOR GT 
;G0 IF GT "9 
j I! V '..' Ill !: 
;i:ij'.5 It. 5)E 
; MERGE 



;G0 IF MORE 
! COUNT TO A 

; f-LT 'J? [iTJLT Z FLAG 
; RF.r.lH.- Ti. :IL 

: RESTORE REGISTERS 



9" 



Figure 1-3. Editing Line Numbers 

It's important to note that the edit line numbers are used 
for editing purposes only and are not used in the program 
(as they are in BASIC) to refer to other source lines. The 
output of the Editor is an assembly-language source file, 
a collection of source lines that represent a source pro- 
gram. This file is stored on cassette tape or disk, depend- 
ing upon the Editor/Assembler. 

The third part of the assembly-language listing is shown 
in Figure 1-4. This is the machine code portion of the 
assembly. When the Assembler portion of the Editor/As- 
sembler processes the source file, the Assembler trans- 
lates the source lines into the corresponding machine code 
form of the instruction. For example, the Assembler 
translates the OR A , . . instruction into a hexadecimal 
"B7". The hex B7 corresponds to a binary 10110111, which 
the Z-80 microprocessor will decode as an OR instruction 
that ORs the contents of the A register with the A register. 
The Assembler automatically translates the symbolic 
source lines into a form that the Z-80 processor can 
recognize, binary ones and zeroes. 
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MEMORY LOCATION 
















FOR INSTRUCTIOIv 


















DATA REPRINTING 








" 


f~ 


INSTRUCTION 














08970 


. ••••••••DECIMA 


. TO is I :: A !r 


CONVERSION SUBROUTINE 






06980 


■ « 


CONVERTS U 


> TO SIX ASCII CHARACTERS REPRESE 






00990 


- * 


DECIMAL NU 


1BER TO BI1 


ARJ. MAXIMUM VALUE IS 






09000 


- B 


EN.TDZ: (HL) = BUFFER CONTAINING ASCII 






090 10 


• S 




(B) 


rfiUMBER OF 


CHARACTERS 






09020 


. s 


E>: 


11: (i!L 


= B 1 1, ill .■•' 


0-65535 






i< •'''.' ;0 


: " 




HZ 


if ;::v;i.i[' 


ASCII CHARACTER GTMEIIW 






090H0 


■ « 


ALL REGIST 


ERS SAVED EXCEPT A,HL 






<< '.' ', 


: 










8590 


C5 


■j 9 Of. (1 


C C t I .'! 


I' v r, I-: 


EC 


;SAVE REGISTERS 


8591 


D5 


09070 






PUSH 


DE 




8592 


DDE5 


09080 






PUSH 


IX 




8591 


DD210000 09090 






LO 


I >: . o 


;rr.T PE2.UIT 


8598 


DD29 


9 1 


2tcr,!, o 


.-■T-'D 


IX, IX 


; INTERMEDIATE" 


859A 


DDES 


■> 1 1 






rusii 


IX 




859C 


DD29 


09 ' 20 






ADD 


IX, IX 




oil 


859E 


DD29 


091 30 






;.r,o 


: r. , : >: 




«B 


85A0 


D1 


9 KG 






POP 


DE 




fSi> v «"5*Si:v'V 


85A1 


DD19 


9 150 






n II 11 


IX, DE 




«10 


85A3 


7E 


09 'SO 






LB 


A, (PL! 




GET CHARACTER 


85 AH 


D6 30 


09 170 






:m:-. 


:<ok 




CONVERT 


85A6 


FAB685 


09 160 






j I' 


li.OSCOYG 




CO IT LT "0" 


85A9 


FEOA 


9 190 






CP 


10 




TEST TO A OT " 


85AB 


F2B685 


09200 






jp 


P, DECOY 




GO IF GT "9" 


65AE 


5F 


09210 






LL' 


E, A 




:;om in l 


85AF 


1600 


9 2 2 






LO 


D,0 




iioi: in no 


85B1 


DD19 


09250 






ADD 


IX, DE 




I'.EII'JE 


85B3 


23 


0924 






LUC 


HL 




85BH 


10E2 


09 .?5'J 






o.n.r. 


li DC OHO 


ICO 11 liiiiil. 


85 B6 


78 


092110 


DECC7 


LL' 


A,B 


; COUNT 70 A 


85B7 


B7 


09270 






on 


ilSSBI 


;SE7 OR PE.'.LT 2 


85B8 


DDE5 


o<ir6o 






PUSH 


S;f;xrKi''4ft i, 3 


; PL'.'.OJLT 10 id. 


85BA 


E1 


9 2 9 






POP 


II L 




85BB 


DDE1 


09-00 






POP 


IX 


; so si oaf »:-.i;isrt 


85BD 


D1 


09 i 10 






PUP 


!.: 




85BE 


CI 


09 320 






POP 


EC 




B5BF 


C9 


09330 






RET 




i BE'! UH:: 



»9ttfi*3B9)} 



Figure 1-4. Machine Code 

The second column of Figure 1-4 is the hexadecimal 
representation of all the assembly source lines. As there 
are two hexadecimal digits per 8 bits (one byte), each pair 
of hex digits represents one byte of the instruction. Z-80 
instructions may be one, two, three, or four bytes long, as 
you can see from the figure. Normally, the assembly-lan- 
guage programmer should know the rudiments of binary 
and hexadecimal representation. If you're not familiar 
with binary or hexadecimal numbers, spend a few hours 
reviewing a basic text on the subject. 



-Hints and Kinks 1-1- 



Binary/Hexadecimal Representation 

Hexadecimal is just a shorthand way to represent 
binary numbers , To convert from binary to hex , 
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group the binary number into 4-bit groups and 
then convert to a hex digit 0-9, A, B, C. D, E, or F. 

Binary 0011 1011 1001 1111 

Hex 3 B 9 F 

To convert back, perform the operation in 
reverse , 

To convert from decimal to binary, divide by two 
and arrange the remainders in reverse order, 
Rl 




21109 

Use the same scheme to convert from decimal to 

hexadecimal . 

To convert from binary to decimal, use ' 'double- 
dabble. ' ' 











*2= 2+1 = 3 



3*1-- 6+0-- G 



6*2= 12+1= !3 



13x2=26+1-- 11 



27*2=54+0 = W 



54x2= 108+1 = 109 



Use the same scheme to convert from hex to 
decimal . 

. , . . I know - Right now you' re saying, ''If 
God had wanted man to count in hexadecimal , he 
would have given him 16 fingers .,..'' 
You'll be surprised, however, at how easy it is 
to work in binary or hex after some practice. 
Soon you ' 11 be balancing your checkbook in it ! 
Hmmmmm , , . Maybe that would help mine . . . 
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The first column of the machine code portion, which is in 
hexadecimal notation, represents the location of the 
machine-code data in memory. The instruction PUSH BC, 
for example, has been assembled at location 8590H. If you 
were to take the machine code from column two and enter 
it into RAM (Random Access Memory) starting at location 
8590H (by using T-BUG or DEBUG), the 48 bytes from 8590H 
to 85BFH would represent the machine-language program 
for the DECBIN subroutine. The location column often 
represents the absolute location of the instructions, 
although with the Disk Editor/Assembler it may represent 
the relative locations from the start (we'll see how in a 
later chapter). 

How the DECBIN Subroutine Works 

Now let's take a look at the operation of DECBIN so we can 
review some basic concepts about Z-80 architecture, 
instructions, and addressing. Before we wrote DECBIN, we 
knew the functions it had to perform — we wanted to 
write some assembly-language code that would take a 
given ASCII string representing a decimal number and 
convert it to binary form. 

Subroutines 

It's convenient to write this code as a subroutine. A sub- 
routine is nothing more than a collection of instructions 
that performs a particular function. Subroutines are 
handy — rather than write the instructions each time we 
need the function, we define the subroutine once so it 
occupies one particular area in memory, and then we call 
it up whenever we need that function in the program. This 
little convenience saves memory space since the code only 
occupies one point in memory. It also saves us the devel- 
opment time of writing the source lines over and over. 
Assembly-language subroutines are functionally identical 
to BASIC subroutines. 

Subroutines also are important for another reason. They 
break the program up into a number of small modules that 
perform well-defined functions. This pattern of modules 
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makes the entire programming task much easier than 
writing a large amount of in-line code. 

We can call the DECBIN subroutine by a CALL instruction 
that is very similar to a BASIC GOSUB statement. The CALL 
instruction jumps to the subroutine but saves the return 
address of the next instruction after the CALL. When the 
RET, or RETurn instruction in DECBIN is finally executed 
at completion, the return address of the instruction after 
the CALL is retrieved or popped from the memory stack, 
and a return is made. 

The appearance of the CALL might be: 

NAME CALL DECB I N i TH I 3 I S THE CALL TO DECB I N 
LD A » 1 5RETURN HERE 



Stack Operations 

The memory stack is an area of RAM set aside for certain 
functions. Whenever a CALL instruction is executed, the 
current address of the Z-80 program counter register is 
saved in the stack area; the address is "pushed" onto the 
stack as shown in Figure 1-5. Whenever a RET instruction 
is executed, the return address is retrieved, or "popped" 
from the stack and put into the program counter to cause a 
return to the instruction following the CALL. The stack is 
also used as temporary storage, as we shall see. The stack 
area set aside for this function and others is typically 100 
bytes. 
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LOW MEMORY 



STACK AREA 

(TYPICALLY 100 

BYTES OR SO) 



HIGH MEMORY 



CURRENT ADDRESS 

AS A RESULT OF 
CALL INSTRUCTION 



STACK 
BUILDS 
DOWN 



Figure 1-5. Stack Action for a CALL/RET 
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Hints and Kinks 1-2 — 

Stack use 

It's easy to remember how the stack works if 
you think of a dinner plate stacker in a 
restaurant. (No, not Ed, the part time counter 
man - the mechanical one! ) As a plate (8 bits 
of data) is placed on the stack, the stack is 
pushed down. As a plate (data) is taken off 
the stack, the stack pops up. Every time a 
CALL is made, two bytes of data, making up two 
address bytes, are pushed onto the stack. 
Every RETurn pops the two bytes. PUSH and POP 
instructions operate similarly. 



HIGH MEMORY 



STACK POINTER 

REGISTER ► 

ALWAYS POINTS 
TO "TOP OF STACK'' 



LOW MEMORY 



PUSH 



POP 



To set the stack pointer, perform the "LD 
SPtXXXX" instruction, where XXXX is some 
(usually) high memory location, as the stack 
1 'builds down' ' . 

Just as every he must have a she, every PUSH 
must have a POP and every CALL must have a 
RET! Otherwise stack will "gobble up" memory 
below it as it digests byte after byte, 
pushing data further and further down! 
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Before we can call the DECBIN subroutine, we must set up 
the subroutine arguments in preparation for the sub- 
routine action. The arguments are what might be popu- 
larly known as the "gozintas" and the "gozoutas." In this 
subroutine, we're entering with a pointer to a string of 
ASCII characters representing decimal digits 0-9 and the 
number of characters in the string. That's the "goes into." 
We're exiting (the "goes out of") with a binary number 
from to 65535 representing the converted result. Also, if 
we detect an invalid ASCII character in the string, such as 
the one in "123$56" — we want to know about it. In the 
case of "123$56", the Z flag in the Z-80 is reset (an "NZ" 
condition). 

When we started writing the subroutine, we had to do 
some thinking about how to pass the arguments. One of 
the arguments is a pointer to a string of ASCII characters. 
The characters are identical to the ones we would get by 
typing in characters from the TRS-80 keyboard. Each 
character takes up one byte, as shown in Figure 1-6. We 
would like to convert the string of characters into the 
equivalent binary number. Since we must put some limit 
on the number to be converted, we chose 65535, a number 
that can be held in 16 bits, which is the size of a Z-80 
register pair. It seems convenient, then, to return the 
result in a Z-80 register pair of 16 bits. 
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LOW MEMORY 

BYTEO 
1 
2 
3 



HIGH MEMORY 



ASCII 'T 



ASCII "2' 



ASCII "3" 



ASCII "4" 



ASCII "5" 



ASCII "6' 



. x 



ASCII STORAGE 
IN MEMORY 



Figure 1-6. ASCII Character Storage 



V 



f 

.'-■ 
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Hints and Kinks 1-3 

ASCII 

ASCII is simply a standardized 7-bit code used 
for uniform representation of character data. 
See the tables in many of the TRS-80 manuals. 
All BASIC strings are stored in ASCII. Data to 
be displayed on the screen or line printer 
must first be converted to ASCII by software. 

Fortunately the ASCII codes for 0-9 and A-Z 
and a-z run in sequence, making it much easier 
to convert. This is not always true of 
character codes. Some peripherals have codes 
based on type-ball position, the phase of the 
moon, or both! 



Passing Arguments 

How would we pass the ASCII string to the subroutine? 
With a limit of 65535, we would have a maximum of 5 
bytes. Although we could pass these five bytes in five Z-80 
registers (or 2V2 register pairs), we'll choose instead to 
pass a pointer to the memory locations that contain the 
string. This pointer value can be held in 16 bits, as any 
TRS-80 memory location can be expressed as a value of 
through 65535. 

The number of bytes in the string may vary from 1 to 5; 
this is also an argument that must be passed to the 
DECBIN subroutine. As this is a small value, it can be 
passed in a single Z-80 register of 8 bits. 

Z-80 Registers 

Any of the general purpose (A, B, C, D, E, H, or L) registers or 
register pairs (BC, DE, HL) could have been chosen to hold 
the arguments. We have chosen HL to hold the string 
pointer and B to hold the count — since HL is convenient 
because many of the instructions use the HL register pair 
as a register indirect pointer to memory locations. B is 
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conveniently used, as a special DJNZ instruction uses B as 
a counter. A typical CALL to the DECBIN might now look 
like this: 

NAME1 LD HL»BUFFER 5ADDRESS OF 

STRING BUFFER 

LD B»5 ;* OF CHARACTERS 

CALL DECBIN 5C0NVERT ASCII 

TD BINARY 

LD A»l JRETURN HERE 
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Hints and Kinks 1-4 

Z-80 Registers 

These are the Z-80 registers accessible to 
TRS-80 assembly-language programmers. A is 
used for many arithmetic operations. The HL 
register pair is used as a ' '16-bit 
accumulator'' for 16-bit arithmetic. 
Selection of either AF or AF 1 is done by 
EX AF>AF'. Selection of either B-L or B'-L' 
is done by EXX, 

Seem like it is easy to get confused about 
which set of registers, prime or non-prime you 
are using? You bet. Much TRS-80 software uses 
only one set. Typically the prime set would be 
used for interrupt processing. There is no 
reason that you should not use both sets, 
however, as long as you keep track of which 



set is 



current 



REGISTER PAIRS 



A F 
BC 
DE 
HL 



D 



! X 



! Y 



PC 



SP 



A' 



B' 



D' 



H' 



F' 



C' 



E' 



U' 



> GENERAL - PURPOSE 
REGISTER (ONLY 
ONE SET ACTIVE, 
EITHER A-L. OR a'-L' 1 



INDEX REGISTER. (USED IN INDEXED ADDRESSING) 



INDEX REGISTER < " 

PROGRAM COUNTER 

CHEEPS TRACK OF CURRENT INSTRUCTION-) 

STACK POINTER 

CPOINTS TO TOP OF STACK AREA) 



INTERRUPT REGISTER 
REFRESH Rf-GISTE 



rER \ 
R I 



NOT NORPIAU.Y 
USED IN TRS-80 
PROGRAMMING 



In the above sequence, the HL register pair is loaded with 
the address of the string buffer, the locations at which the 
ASCII characters are stored. Note that the LD HL >XX 
instruction (see Appendix II) is an immediate-load type 
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instruction that loads a 16-bit value into the HL register 
pair. In this case, the assembler will load a 16-bit address 
corresponding to the location of label BUFFER into HL. We 
have loaded the B register with 5 as a typical string 
length. The CALL is then made to the DECBIN subroutine, 
with a return after the conversion to the instruction 
following the CALL. 

Algorithm for DECBIN 

Now let's get into the operation of DECBIN itself. The 
sequence of operations for DECBIN goes something like 
this: 

1. Clear a result variable. 

2. Get an ASCII digit from memory, starting from the 
leftmost digit of the string. 

3. Convert the ASCII digit to binary. (Since an ASCII 
"O" through "9" is represented by hexadecimal 30 
through 39, this involves subtracting 30H from the 
ASCII digit.) 

4. Add the result of the subtract, binary 0-9, to the 
total. 

5. If this is the last ASCII digit, you're done. If it's not 
the last digit, multiply by 10 and go back to step 2. 

We've used a slightly modified version of this algorithm 
in DECBIN. Rather than checking for the last ASCII digit 
and then multiplying by 10, we'll multiply by 10 as an 
initial action. This process is illustrated in Figure 1-7, for 
an ASCII string of 5 digits. 
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31 H 

32H 

~33TT 



34H 



35H 



ASCII "12345' 



STEP RESULT RESULT*10 ASCII DIGIT DIGIT-30H ADD TO RESULT 



1 








31 H 


1 


1 


2 


1 


10 


32H 


2 


12 


3 


12 


120 


33H 


3 


123 


4 


123 


1230 


34H 


4 


1234 


5 


1234 


12340 


35H 


5 


12345 



Figure 1-7. Algorithm for DECBSN 



DECBIN — Detailed Analysis 

Now let's go through the DECBIN subroutine to see how 
this is implemented in code. The first nine lines of the 
subroutine are comment lines describing the action of the 
subroutine, the entry conditions, and the exit conditions. 
The remainder of the subroutine implements the 
algorithm. 

The name of the subroutine DECBIN, is expressed by the 
label opposite the first instruction mnemonic. During 
assembly time, this label will be equated to the location of 
the subroutine, and any CALL DECBIN will assemble as a 
CALL to the proper absolute location. 
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—Hints and Kinks 1-5— 

Symbol Table 

As the Assembler does its work, it builds a 
symbol table in memory. Every symbol 
encountered is put into the table as a 
six-character name and associated address 
value. Any references to the symbol cause the 
Assembler to search the symbol table for the 
value of the symbol. 



SYM80L. 



DEC 020 



DEC 040 



DEC 070 



EDD tifefe 



EDD 010 



ENN fctfe 



FOO fefeti 



VALUE 



8000 



8XXX 



8XXX 



FFFF 



<?XXX 



<?AAF 



7XXX 



9ABC 



USUALLY CORRESPONDS 
TO LOCATION OF LABEL 
IN MEMORY 



AN "UNRESOLVED SYMBOL" 
NOT YET ENCOUNTERED IN 
SOURCE LINE. OR COULD ALSO 
BE "UNDEFINED" 



A.. . OH, NEVER MIND. . 



The first three instructions PUSH the BC and DE register 
pairs and the I X register onto the stack, which allows the 
stack to be used as a temporary storage area. The contents 
of BC » DEi and I X > six bytes in all, will be saved in the 
stack area as shown in figure 1-8. They will be retrieved 
with subsequent POP instructions. "Why," you ask, "are 
the contents of B C > D E » and I X saved?" 

The answer is that it's convenient for the programmer to 
CALL subroutines with data in the Z-80 general purpose or 
other registers without having to worry about those 
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LOW MEMORY 



HIGH MEMORY 



IX U 



E 
D 



C 
B 



6 BYTES FOR 
3 PUSHES 



Figure 1-8. Stack Action for PUSH/POP 



registers being used and the data being destroyed. As 
5 > DE i and IK are used in the processing of DECBIN » 
their initial contents are saved in the stack at the 
beginning of the subroutine. Now the registers can be used 
for calculations and intermediate results during the 
processing of the subroutine, and their contents can be 
restored just prior to the RETurn. Of course any registers 
that are used to pass back the results of the subroutine 
would have new contents anyway and should not be saved 
in the stack. 

The LD I X > instruction clears the IX index register to 0. 
IX will hold the intermediate results of the conversion. 

The assembly-language code from label DEC040 through 
DJNZ DEC0 40. . represents the main body of the 
subroutine. It is a loop (and the remarks are indented to 
indicate the loop condition). The number of times through 
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the loop is determined by the number of ASCII digits to be 
processed. Five digits would involve five iterations, four 
would be four iterations, and so on. 

The first order of business is to take the current contents 
of the IX register and to multiply it by 10. Although we 
could CALL another subroutine that performs a multiply, 
we choose to do it an alternative way by a "shift and add" 
technique. First we perform the ADD IX > IX, which adds 
the contents of the IX register to itself. Any number added 
to itself doubles the number, and that's the case here. The 
number*2 is then is PUSHed into the stack by the 
PUSH IX instruction. After the PUSH, the number*2 is in 
both IX and the stack. Two more ADDS change the 
contents of IX to number*4 and number*8, respectively. 
The next instruction, POP DE, pops the number*2 value 
from the stack and puts it into register pair DE. Now an 
ADD of IX and DE is done with the result going to I X. We 
are adding (number*8 + number*2), which is the same as 
number*10. In effect, we've multiplied the contents of IX 
by 10. 

The L D A » ( H L) instruction is a LoaD instruction that 
loads the A register with the contents of a memory 
location. The HL register pair is used as a register 
indirect pointer to the memory location to be loaded. If, 
for example, HL contained 9000H, the contents of memory 
location 9000H would be loaded into the A register. The 
parentheses around the ( H L ) indicate that a memory 
location, rather than an immediate value, is involved in 
the instruction. 
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As we entered the subroutine with the HL register 
pointing to the first (leftmost) byte of the string, the first 
execution of LD A » ( HL ) would result in the first ASCII 
character of the string being loaded into the A register. 

The ASCII character in A is now converted from hex 30 
through 39 (ASCII "0" through "9") to a binary value of 
through 9 by subtracting 30H. An ASCII "5", for example, 
would produce a binary value of 35H-30H = 5. 

There is one problem here, however. If the ASCII character 
is not 30H through 39H, the result will be incorrect. We 
chose to check the validity of the ASCII string in the 
subroutine, so we'd best do that right now. If the result of 
(ASCII character-30H) is less than 0, then the ASCII 
character was less than 30H. If the result of (ASCII char- 
acter-30H) is greater than 9, the ASCII character is greater 
than 39H. 

When we performed the SUB 3 OH, the set of flags in the 
Z-80 was set according to the result of the subtract. If the 
result was 0, the Z flag was set; otherwise, it was reset 
(NZ). If the result was positive the Sign flag was reset (P); 
otherwise, it was set (M or minus). Similarly, the other 
flags (half-carry, carry, parity/overflow, add/subtract) were 
affected. The flags are not always affected by an instruc- 
tion — LoaDs never affect flags, for instance. However, 
many instructions, especially adds and subtracts, do affect 
the flags according to the results of the instruction. 



31 



— Hints and Kinks 1-6- 
Flags 



Flags are a collection of individual bits 
grouped as the "flags register." Flags are 
used to test results of instructions by 
conditional jumps. Some instructions (LDs, 
PUSH, POP, RET, others) never affect the 
flags. Other instructions (ADDs, SUBs, CP) 
always affect the flags while still other 
instructions only affect certain flags. See 
Appendix II . 

Don't hesitate to use instructions that don't 
affect the flags before testing the flags with 
conditional jumps. Just be certain which 
instructions affect which flags - there are 
some surprises here! 



A 


F 


A' 


r 

















FLAGS REGISTER 



5Z-H- %H\C 



SIGN (S) IF RESULT-*-, 1 IF - 
ZERO (Z) IF RESULT a* 0, 1 IF 
1 IF RESULT = 

HALF CARP* - NOT GENERALLY 
(H) USED BY 

PROGRAMMER 

PARITY/OVERFLOW (?/V) 

IF ODD PARITY, 

1 IF EVEN PARITY OK 

IF NO OVERFLOW OR 

1 If OVERFLOW 

ADD/ SUBTRACT CN} - NOT 

GENERALLY USED BY 

PROGRAMMER. 
CARRY (C) IF CARRY, 

1 \F NO CARRY 



We can test the result of the subtract for a minus condition 
by the J P M »DEC070 instruction. If the result of (ASCII 
character-30H) was negative, the Sign flag will be set (M), 
and the instruction will jump on the M condition to label 
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DEC070. If the result was positive, the jump will be 
ignored, and the next instruction in sequence will be 
executed. If the result was negative, the jump to DEC070 
will cause the subroutine to terminate prematurely based 
on the invalid ASCII character. 

After the conditional jump, we make another test. The 
C P 10 instruction compares the result to 10. A compare is 
essentially a subtract of an 8-bit value from the contents of 
the A register. Like a subtract, the flags are affected and 
can be used for conditional branching. Unlike a subtract, 
the contents of A remain unchanged; the result is 
discarded. In this case the value to be subtracted is an 
immediate value of 10. If the Sign flag is set after the CP, 
the conditional jump JP P »DEC070 will cause a jump to 
location DEC070 to terminate the subroutine because of an 
invalid ASCII character. Otherwise the next instruction in 
sequence will be executed. 

Assuming that the ASCII character was valid, we now have 
a binary value of 0-9 in the A register. The L D E » A copies 
that value from A into the E register. The next 
instruction, LD D ,Q, loads the D register with a value. 
In fact, the DE register pair is now loaded with the value 
0-9. If the D register were not cleared by loading 0, the DE 
register pair would contain garbage in the D register, and 
DE could not be used in further operations involving the 
binary value of 0-9. 

Now the binary value in DE is added to the intermediate 
result in IX. If this is the first time through the loop, IX 
now contains the binary value of 0-9. If this is the second 
time through the loop, IX contains A1*10 + A2, where Ax is 
the first converted ASCII value and A2 is the next. The 
third time produces Al*ioo + A2*io + A3, and so on. 

The INC HL instruction adds one (INCrements) to the 
contents of the HL register and puts the results back into 
HL. (No flags are affected, by the way.) Initially, HL 
pointed to the leftmost character in the buffer. Each time 
through the loop, HL is adjusted to point to the next ASCII 
character so it may be processed in turn. 
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The D JNZ D ECO 40 is a unique instruction. It operates as 
follows: The contents of the B register is decremented by 
one. If the result of the decrement is not zero (NZ), the 
instruction jumps back to the specified jump address, in 
this case DEC040. If the result of the decrement is zero, 
the next instruction in sequence is executed. The 
mnemonic stands for "Decrement and Jump if Not Zero." 

We entered the DECBIN subroutine with a count in the B 
register of 1 to 5, representing the number of ASCII digits 
to be converted. Each time through the loop, the count in 
B is adjusted downward by one until zero is reached. As 
long as the contents of B after the decrement is not zero, 
the loop is reentered at DEC040. 



■Hints and Kinks 1-7- 
Loop Trace 



Here's a ''trace'' of individual registers 
through part of the DECBIN routine. This type 
of trace can be done with paper and pencil to 
' 'play computer' ' and verify during ' 'desk 
checking' ' that the program works as desired. 



A 


IX 


31 
i 



i 


i 


1 
2 




4 




6 


50 


10 


2 


12 




24 



DE 



HL 

BUF 
BUF+I 



_B 

3 
2 



BUF+2 



Right now you're probably asking. 



'Must 



assembly-language programming be this 
tedious?'' Well, yes... Look at the rewards, 
though-fast speed, compact code, the 
challenge. .uh. .maybe I'll go back to BASIC, 
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After the loop has been completed, IX contains the result 
of the conversion of the ASCII string. The LD A »B 
instruction loads the A register with the contents of B. If 
the count in B is 0, the loop has been completed for all 
ASCII digits. If B is other than 0, a premature jump was 
made to DEC070 because of an invalid ASCII digit. After B 
has been loaded to A, we execute an OR A instruction. 
This instruction is a commonly used instruction to test the 
contents of A. ORing any number with itself does not 
change the number. The OR A takes the contents of the 
specified register (A) and ORs it with the A register. When 
the specified register is A, this ORs A with itself. The 
important thing here, though, is that the flags are set on 
the result of the OR. The Z flag is set if the result in A is 
zero or reset if the result is non-0. Since A contains the 
previous count in B, the Z flag is set if B was zero 
(successful termination of loop) or reset if B was non-zero 
(invalid ASCII character). As the following PUSH, POP, 
and RET instructions do not affect the flags, the Z flag 
will remain set or reset on the return to the calling 
program. 

As the result is in IX, and we specified the result in HL on 
exit, a transfer must be made. A PUSH IX followed by a 
POP H L pushes the contents of IX onto the stack and then 
immediately pops it back to the HL register pair. This is a 
common way to transfer the contents of one register pair 
to another as there is no LD from one register pair to 
another. The three POPs at the end of the subroutine 
restore the original contents of IX, DE, and BC. Note that 
the order of the contents is opposite from the way they 
were initially pushed onto the stack as the stack is a "last 
in, first out" operation. 

The RET instruction pops the return address from the 
stack, puts it into the program counter, and causes a 
return back to the calling program at the next instruction 
after the CALL DECBIN. The HL register pair now contains 
the result of the conversion (0-65535), and the Z flag is set 
if the conversion was correct or reset if an invalid ASCII 
character was encountered. 
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The DECBIN subroutine is probably a typical TRS-80 sub- 
routine in terms of complexity and size. If you have 
trouble with some of the concepts involved with DECBIN, 
review the appropriate material in TRS-80 
Assembly -Language Programming, and continue to follow 
the examples closely in future chapters. We'll attempt to 
explain any subtleties as they come up. 
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Chapter Two 

Assemblers and Asseinbling- 

EDTASM 

Radio Shack has two assemblers available for the TRS-80, 
the cassette-based Editor/Assembler and the disk-based 
Disk Editor/Assembler. To make things easier, we'll refer 
to the former as "EDTASM" and the latter as "the Disk 
Assembler." In this chapter, we'll be primarily discussing 
EDTASM. Some of our discussion will also apply to the Disk 
Assembler. The two assemblers are similar in that they 
both assemble Z-80 assembly-language code, but they are 
different in the ways they load the code. In this book we'll 
be talking about using both EDTASM and the Disk 
Assembler, and to keep things straight, we'll note any 
differences in format or technique as we go along. 

EDTASM is more of a "single-user" assembler for short 
programs, while the Disk Assembler is normally used for 
more advanced work and larger programs. Chapter 13 has 
a large program that has been assembled by EDTASM, and 
we'll use that program for frequent examples in this and 
other chapters. 

A Look At EDTASM 

For openers, let's take a look at EDTASM. Some of this 
material might be familiar to you from using EDTASM or 
from reading TRS-80 Assembly -Language Programming. 
The operations in EDTASM are more straightforward than 
some of the advanced features of the Disk Assembler, so 
we'll start with the operation of EDTASM and then use that 
as a base for discussing the Disk Assembler. 
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As we know from Chapter 1, EDTASM includes both an 
Editor and an Assembler. The Editor has commands and 
subcommands similar to the Editor in Level II BASIC. 
Using these commands, an assembly-language source file 
can be initialized, modified and written out to cassette 
tape for subsequent assembly by the Assembler portion of 
EDTASM. (As an alternate approach, the source lines can be 
assembled directly from the buffer in memory to check for 
a valid assembly before writing the file out to cassette.) 
We won't go into the editor commands and subcommands 
as they're covered both in the EDTASM User Instruction 
Manual and in our previous book. 



—Hints and Kinks 2-1 — — 

Typical Edit Sequence 

Here's a typical edit sequence to create an 
assembly-language source file with EDTASM; 

1. Load EDTASM. 

2. * 1 100 1 10 starts lines at 100 with 
increments of 10 . 

3. Enter source lines. Each line is 
terminated by an ENTER. Use tabs 
between labels, op-codes, operands, 
and comments. 

4. Hit BREAK. This brings you back to the 
Editor command mode. 

5. W NAME. Write file to cassette with 
name NAME . 

See the Editor/Assembler User Instruction 
Manual for directions on Editor commands and 
subcommands . 



What we are going to cover in this section are the 
subtleties of EDTASM source language syntax and 
pseudo-ops. Syntax (please, no bad jokes) refers to the 
rules of structuring assembly-language lines, while 
pseudo-ops are commands to the assembler in the op-code 
field of the assembly-language line. For clarity, we'll use 
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examples from a program assembled by EDTASM in the last 
section of this book. 

Source Line Syntax 

Figure 2-1 shows a typical section of code for the MORG 
program. The syntax is fairly straightforward. The source 
lines are free format in that there are no specified 
columns for labels, op-codes, operands, and comments. You 
can write source code in any convenient format as long as 
there's a space between each field, as long as an op-code 
does not start in column 1, and as long as a semicolon 
precedes a comment. 







COMMENT LINE STARTED 










BY SEMICOLON 






SEMICOLON PRECEDES 








I 






COMMENT FIELD 
/ 






01500 


f 






/ 






01510 


; «**«*« 


•**f ill 


•••DEFINE MESSAGE «l ROU TIUE«««»«»»«««»««»«« 






01520 










80EB 


2AE985 


01530 


DEFINE 


LD 


HL, (CURCUR) 


;GET CURRENT CURSOR 


80EE 


22EB85 


01510 




LD 


{ LSTCUR ) , HL 


;SAVE 


80F1 


CDFB83 


01550 


DEF005 


^CALL 


CLRCOH 


; CLEAR COMMUNICATIONS AREA 


80F1 


21F586 


01560 




*LD 


jHL,MSG5 


1 DEFINE MESSAGE 


80F7 


01>t03F 


01570 




LD 


« BC, LINE13 


1LIKE 13 


80FA 


CD6D83 


01580 




CALL 


/ DSPHES 


IDISPLAY DEFINE MESSAGE 


80FD 


0601 


01590 




LD / 


B, 1 


;1 CHARACTER 


80FF 


CD0D81 


01600 




CALL/ 


INPUTS 


;GET CHARACTER 


8102 


C27F81 


01610 




JP / 


NZ.DEF050 


;GO -IF GT 1 


8105 


0601 


01620 




LD/ 


B, 1 


;1 CHARACTER 


8107 


CD9085 


01630 




CM.L 


DECBIN 


; CONVERT TO BINARY 


810A 


C27F81 


01610 




ik 


NZ.DEF050 


;G0 IF ERROR 


810D 


7D 


01650 




LD 


A, L 


;MSG i NOW IN A 


810E 


21C987 


01660 




/LD 


HL,HSG1 1 


; INPUT MESSAGE 


8111 


01803F 


01670 




LD 


BC, LIHE11 


;LINE 11 


81 ID 


CD6D83 


01680 




CALL 


DSPMES 


;DISPLAY MESSAGE 


81 17 


2AEB85 


01690 




LD 


HL,(LSTC0S ) 


;GET OLD CURSOR 


81 1A 


22E985 


01700 




LD 


(CURCUR) , HL 


; RESTORE 


81 1D 


F5 


01710 




PUSH 


AF 


;SAVE MESSAGE S 


81 1E 


CDC782 


01720 




CALL 


FNDHSC 


;GET ADDRESS OF MESSAGE 


8121 


202A 


01730 




JR 


NZ.DEF035 


;GO IF HO CURRENT MSG FOR 






01710 


i/CUBREHT HSG 


FOR II IN HBUF - 


MUST DELETE 


8123 


E5 


1 7 5 j 




PUSH 


HL 


;SAVE START 






TAB (RIGHT ARROWI USED 










TO SPACE TO PRESET 










FIELDS (OPTIONAL) 









Figure 2-1. Assembly Source Code 

Because we like neat listings, we've used the right arrow 
tab function in this and other codes to tab to the next tab 
position. You might also notice that when loops occur, 
we've indented the loop in the comments column to make 
them easier to follow. 
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A small sermon here from one who has learned the hard 
way: you can't use too many comments in a listing. 
Invariably I find myself looking at assembly-language 
code months later and wondering why I did a particular 
thing. Comments help! 

The labels for assembly-language lines are optional. In 
most of the programs here, we've used the following 
general rules for labels: 

1. The first label of a subroutine or main section of 
code is a descriptive name for the code, such as 
SCROLL or CLRCOM. 

2. The labels in that particular section of code use the 
first three letters of the descriptive name plus 
three digits. 

3. The digits in the labels are generally in ascending 
order. For example, I N P 2 follows I N P 1 . 

Of course, you can use any scheme you wish for labels. An 
approach like the one above does make it easier to locate 
code and ultimately makes coding easier. 

The op-codes in the source code follow standard Zilog 
mnemonics. These are the mnemonics that Zilog, the 
designer of the Z-80, defined for each instruction. 

The operands also follow the Zilog format for arguments. 
This format uses parentheses to indicate a memory 
address and no parentheses to indicate an immediate 
value; it also fixes the number of arguments for any par- 
ticular instruction. Let's illustrate that first point about 
parentheses: If a source line appears such as 
LD HL » (38B0H), the parentheses indicate that the 
contents of memory location 3880H (and 3801H) will be 
loaded into the HL register pair. But if a source line, (such 
as LD HL »3880H) appears, the lack of parentheses 
indicates that the value 3880H will be loaded into the HL 
register pair. 
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Hints and Kinks 2-2 

Flag Mnemonics 

The mnemonics used in conditional jumps refer 
to flag conditions. Typical instructions might 
be 

JP NZ,L0CN ;JUMP IF NOT ZERO 
JR C.LOOP ;JUMP IF CARRY 

The mnemonics and associated flag settings 
are : 



MNEMONIC 


FLAG SETTING 


NZ (non-zero ) 


Z = 


Z (zero) 


Z=l 


NC (no carry) 


C = 


C (carry) 


C = l 


PO (parity odd) 


P/V = 


PE (parity even) 


P/V = l 


P (sign positive ) 


s = o 


M (sign negative ) 


S = l 



There are no conditional jumps for H 
(half-carry flag) or N (add/subtract flag). 
These are used internally by the Z-80 in 
instruction execution. 

The most frequent conditional jump is on the Z 
flag, next the carry, next sign, next the 
''overflow'' condition of P/V, and next the 
''Parity'' condition of P/V. 



Similarly, LD A t (HL) means that HL is used as a 
memory indirect pointer register and that the contents of 
the location pointed to by HL will be loaded into A. 
LD A t B, of course, means the contents of B will be loaded 
into A. Note that the format for Z-80 instructions in the 
operand field is always destination, source. The source 
operand, whether memory or register, is always last, while 
the result, or destination, is always first. 
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Constants 

Now a word about numeric constants. As you've probably 
noticed, we've been using H right along as a suffix for a 
hexadecimal constant. Any hex value must have an H as a 
suffix to indicate the data is hexadecimal. If the first digit 
of the hexadecimal constant is A through F, legitimate hex 
digits, then a must be added before the hex digit. It's 
easy to see why this is so since the Assembler must be able 
to differentiate between constants and labels. 

If a constant has no suffix, it's assumed to be a decimal 
constant. A suffix of D signifies a decimal constant (so 
there's no point in using it!), and a suffix of signifies an 
octal constant (so there's probably no need for this suffix 
either, since you'll probably never require octal constants). 

If a character is bracketed by single quotation marks, it's 
interpreted as an ASCII character. To load the B reg- 
ister with an ASCII A, for example, we'd have 
LD B,'A'?L0AD A INTO B REGISTER. 

We'll discuss expressions involving constants and sym- 
bols after we look into the use of pseudo-operations. 

Pseudo-Operations 

Most assembly-language source lines are generative 
types of lines. A mnemonic representing a Z-80 op-code 
generates the corresponding machine code for that 
instruction at that point in the assembly. However, there 
are a number of commands to the assembler, called 
pseudo-operations or "pseudo-ops," that don't generate 
instructions. Instead, they inform the Assembler of certain 
actions to be taken, or they create data values. 

The first of these is the Origin, or ORG, pseudo-op. The 
Origin informs the Assembler that the following code is to 
be assembled for a particular memory location. For an 
example of this, look at Figure 2-2, where MORG has been 
assembled to run at 8000H. When the Assembler en- 
counters the ORG statement, it will set an internal 
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assembly location counter to the value of the operand in 
the ORG statement. This assembly location counter will be 
adjusted by the length of each instruction as an 
instruction is assembled. Unless the code is relocatable, 
code produced for one Origin will not run anywhere else in 
memory, since there are addresses in many instructions 
which are absolute addresses. (We'll discuss relocat- 
ability shortly.) 



SETS ASSEMBLY LOCATION COUNTER TO 8000H 



8000 




00100 




one 


-OOu!! 








00110 


iHORG-0820 










00120 


■ S*«*»i«*»*« 


•••HORSE CODE GENERATOR PROGRAM" •••••••"•••• • 






00130 


i 












001HO 














00150 


; »**•*! 


mil 


•••••••••SYSTEI- 


EQU ATES»«««»» •••••••••••••••• 






00160 


; 








3C00 




00170 


SCREEN 


EQU 


3C00B 


ISTART OF VIDEO DISPLAY 


3 CIIO 




001 60 


LINE1 


EQU 


SCREEII + 611 


ISECOND LINE 


3EC0 




0190 


L 1 11 E 1 1 


EQU 


SCREEN+70H 


; TWELFTH LINE 


3F00 




00200 


LIKE12 


EQU 


SCR£EU*768 


; THIRTEENTH LINE 


3F40 




00210 


L 1 1. E 1 3 


EQU 


SCREEH+832 


;FOUTEENTH LINE 


3F80 




00220 


L I K E 1 1| 


EQU 


SCREEN+896 


; FIFTEENTH LINE 


3FC0 




00230 


LINE15 


EQU 


SCREEN+960 


1 SIXTEENTH LIKE 


0002 




00210 


ENTER 


EQU 


2 


i ENTER CHARACTER 


0001 




00250 


CLEAR 


EQU 


1 


ICLEAR CHARACTER 


006H 




00260 


DBDEL 


EQU 


100 


;DEBOUNCE DELAY IN IIS 


0065 




00270 


DBDELP 


EQU 


DBDELi-1 


jDEEOUNCE DELAY+I HS 


00OA 




00280 


KLDEL 


EQU 


10 


IHAIN LOOP DELAY IN 1/10 HS 


03C0 




00290 
00300 


SPEEDF 


EQU 


960 


iFIKAGLE FACTOR FOR SPEED 






00310 


; *»«*«*t«f«« 


•••••••••HORSE 


EXECUTIVE**««»» t8 « •••••«••••*• 






00320 










■ ' 


F3 


00330 


START 


CI 




;DISABLE INTERRUPTS 


8001, 


k 3 1 5 9 9 1 


00310 




LD 


SP, TOPS 


;SET STACK POINTER 


800H 


,1 1 EA88 


00350 




LD 


DE.11BUF 


; MESSAGE BUFFER ADDRESS 


8007 


\010B0A 


00360 




LD 


BC2571 


12571 BYTES 




FIRST INSTRUCTION 












ASSEMBLED AT 












LOCATION 8099H 











Figure 2-2. ORG Use 

The END pseudo-op marks the end of the source file and is 
self-descriptive. If the END has an operand, use it as the 
starting point in the program when the program is loaded 
as in END START. 

There are three pseudo-ops that generate data in EDTASM. 
The first of these is DEFB, or DEFine Byte, which generates 
a single 8-bit value. The next is DEFW, or DEFine Word, 
which generates a 16-bit value. The last is DEFM, or 
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DEFine Message, which generates a string of ASCII 
characters that usually represents a message used in the 
program. Each of these three pseudo-ops can have a label, 
if desired. Examples of each are shown in Figure 2-3. 



85DC 0000 
85DE 00 
85DF 00 
85E0 00 
85E1 D201 
85E3 2E16 
85E5 9001 
85E7 B001 
85E9 003C 
85EB 003C 
85ED 0000 
85EF 20 
85E0 F592 
85F2 F592 



85F1 20 

20 20 
20 20 
20 20 
20 20 
52 17 
20 20 
20 20 
20 20 

8631 13 

18 11 
20 13 
15 52 
51 20 



09600 

09610 

09620 

09630 

09610 

09650 

09660 

09670 

09680 

09690 

09700 

09710 

09720 

09730 

09710 

09750 

09760 

09770 

09780 

09790 

20 20 20 

20 20 20 

20 20 20 

20 2A 2A 

2A 2A 2A 

20 20 20 

20 20 20 

20 20 20 

09800 

52 3D 53 

18 11 52 

20 20 53 

30 2D 39 



•••••••WORKING STORAGE' 



IHP1 

PBINTF 

LPFTF 

CHARCT 

SEED 

DOTO 

DASH0 

CURCUR 

LSTCUR 

TSLC 

LASTR 

IBUFL 

IBUFN 



DEFW 
DEFB 
DEFB 
DEFB 
DEFH 
DEFW 
DEFH 
DEFW 
DEFW 
DEFW 
DEFW 
DEFB 
DEFW 
DEFW 











1231 

5678 

100 

1200 

3C00H 

3C00H 



IBUF 
IBUF 



TEMPORARY STORAGE 
PRINTER FLAG:0=0FF, 1=ON 
LP 1ST TIME FLAG:0=1ST TIME 
LP CHARACTER COUNTER 
DEFADLT SEED 

:DOT OH TIME (3 WPM DEFAULT) 
;DASH OH TIME (3 WPM DEFLT) 
:CURRENT CURSOR POSITION 
;LAST CURSOR POSITION 
iTIME IN MS SINCE LAST CHAR 
;LAST RANDOM CHARACTER SENT 
j POINTER TO LAST IBUF SLOT 
; POINTER TO NEXT IBUF SLOT 



•••••••••••SYSTEM MESSAGES** 



IE 11 20 ID 53 



MSG1 DEFM 

20 20 20 

20 20 20 

20 20 20 

2A ID IF 

20 20 20 

20 20 20 

20 20 20 
20 20 

DEFM 

15 IE 11 

11 13 51 

18 19 16 

3D 53 15 

17 20 IE 



!••••••• 



»««MORG»»» 



20 09810 D 

20 53 18 19 16 51 20 52 
3D 53 15 HE 11 20 52 11 
IE 11 IF ID 20 20 53 18 

19 16 51 20 11 3D 11 15 

16 19 IE 15 20 ID 53 

17 09820 D 

20 20 20 53 18 19 16 51 
20 53 3D 11 15 16 19 IE 



•CHAR=SEND CHARACTER SHIFT 0-9=SEND HSG N 1 



SHIFT R=SEND RANDOM SHIFT D=DEFINE MS' 



SHIFT S=DEFINE SPEED SHIFT P,N=PRINT' 



15 20 53 50 15 15 11 



20 53 18 19 16 51 20 50 
2C IE 3D 50 52 19 IE 51 



86AE 20 09830 
IF 52 20 IE IF 



Figure 2-3. DEFB, DEFW, DEFM Use 

The DEFW generates 16-bits of data in standard Z-80 word 
format. In this format, the least significant byte of the 16 
bits is stored in the first byte, and the most significant 
byte of the 16 bits is stored in the second byte. If you look 
at the machine code produced in Figure 2-3, you'll see the 
hexadecimal data generated in CURCUR DEFW 3C00H, 
for example, is arranged as 00 3 C. 
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Hints and Kinks 2—3- 



Sixteen-Bit Data Format 

Many programmers get confused over 16-bit 
data format. When a 16-bit piece of data is 
stored in memory, it is always stored least 
significant byte followed by most significant 
byte, The code 



LD 
LD 
LD 



;locn) ,HL 
;locn + 2) ,DE 
;locn+4) ,bc 



STORE HL 
STORE DE 
STORE BC 



would store data in the LOCN area as follows: 



LOCN+0 


L 


+ 1 


H 


+ 2 


E 


+ 3 


D 


+ ^ 


C 


+ 5 


B 



Data in the stack (say, a PUSH HL) is stored 
the same way. 

When data is retrieved (LD DE,(L0CN+2) or 
POP BC) it's put back into the registers in 
identical fashion, (Whew! What if the 
designers had chosen to retrieve it in 
opposite fashion, . , . Thank goodness for cool 
heads in Silicon Valley, . , ) . 



The DEFM simply generates a one-byte ASCII character for 
every character in the string. The string is started and 
terminated by a single quotation mark ('). 

The DEFS (DEFine Storage) pseudo-op reserves a number of 
bytes at the current assembly location. If, for example, you 
want to define a table that would be filled with values 
during program execution, you might have the following 
code: 



TABLE DEFS 100 



5 100-BYTE TABLE 
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The assembler would then increase the assembly location 
counter by 100, bypassing 100 bytes. Note that the 
machine code bytes produced for a DEFS consist of garbage, 
or unknown, data. A DEFS does not fill the vacant space 
with zeroes, all ones, or anything; it just leaves whatever 
is there to begin with. 

The last pseudo-op is EQU, or EQUate. To understand this 
pseudo-op, you need to understand the processing that the 
Assembler goes through. The Assembler makes two (or 
more) passes through the source file. After the first pass, 
it has assembled a symbol table of all labels with a 
corresponding numeric value for each symbol. (This is the 
information displayed at the end of the program listing.) 

In most cases, each symbol has a value that represents the 
assembler location counter value, which is essentially the 
location at which the instruction or data for that symbol 
will reside. The EQU pseudo-op, however, can force the 
Assembler to equate a label either with a numeric value or 
another label. This is the case for CDTAB as shown in 
Figure 2-4. CDTAB is equated to C TAB. In other words, the 
value associated with CTAB — the location of 8812H — will 
also be used for symbol CDTAB. In this case, we made the 
association because the CDTAB contained the same data as 
the first 44 locations of CTAB. 



10080 
10090 
10100 
10110 
10120 



».«»»««»«»»»ii«»CTAB CHARACTER TA BLE« » *• »»" »•••» •• « 

TABLE OF CHARACTERS TO BE SENT II) RANDOM MODE. 
DISTRIBUTION DOES NOT CORRESPOND TO THAT IN NOR- 
MAL TEXT. SPACE CHARACTER NOMINALLY EVERY 5 TH 
CHARACTER. 



• THESE BYTES ARE CDTAB! 



10130 : 

8812 11 10U0 CTAB DEEM • ABCDEEGH I JK LMNOPQRSTU VWXY Z0 1 231 56 7 89 . . ?/ - 

.1 2 :\\ *■: 15 ~i ■•- Hi ■•<■•' 

HA HE IIC l|D It E li T 50 51 

52 53 5': 55 56 57 58 59^3— 

5A 30 31 3S 33 :■■> 33 ':■'■ 

37 38 39 2E 2C 3F 2F 2D 

20 3D 3B 

883E 30 10150 DEFM '012311567 89.,?/- = ; ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 

31 32 33 31 35 36 37 38 

39 2E 2C 3F 2F 2D 20 3D 

3B 11 12 13 11 15 16 17 

18 19 1A IB 1C ID IE IF 

50 51 52 53 51 55 56 57 

58 59 5A 

886A 20 10160 DEFM • ' 

20 20 20 20 20 20 20 20 

20 20 20 20 20 20 20 20 

20 

887C 11 10170 DEFM ■ ABCDEFGH I JKLHNOPRSTU V Y ' 

12 13 11 15 16 17 18 19 

1A IB 1C ID IE IF 50 52 

53 51 55 56 59 
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««*»#«*»»*»*»»»t»*CDTAB CODE TABLE* **** * » *#»**« ottli » 

TABLE OF VALID ASCII CHARACTERS TO BE TRANSMITTED. 
INDEX TO CHARACTER USED TO OBTAIN TIMING CODES 
FROM TTAB. 



10180 

10190 

10200 

10210 

10220 

10230 

8812 102*0 CDTAB EQU CTAB ;SAME DATA 

002C 10250 CDTABS EQU 114 ;SIZE OF DATA 

10260 i 



Figure 2-4. EQU Use Example 1 

As figure 2-4 also shows, you can use the EQU pseudo-op 
for CDTABS. CDTABS is equated to 44. Every time CDTABS is 
referenced, as in LD B t CDTABS, the value loaded for 
CDTABS will be 44. LD 5* CDTABS would therefore 
become equivalent to LD B »44. Equates are used in this 
fashion so an easily-remembered symbolic name can be 
given to constants such as size of tables, addresses of I/O 
devices, etc. 

Another use of EQU is shown in Figure 2-5. Here MBUF 
(Message Buffer), has been equated to $. * is a special 
symbol that represents the current value of the assembler 
location counter. After the MBUF equate, MBUF would be 
stored in the symbol table as the value 88EAH. The next 
line, ENDM EQU $ + 2571, equates the label ENDM to 
$ + 2571. Since the assembler location counter did not 
change from the previous equate (no instructions or data 
were generated), ENDM is equated to 88EAH+2571 or 
92F5H. This little trick is synonymous to: 

MBUF EQU $ 

DEFS 2571 
ENDM EQU $ 
and is quite commonly used. 



107 80 

10790 

10800 

10810 

88EA 10820 MBUF EQU $ 

92F5 10830 ENDM EQU $+2571 

108M0 i 



Hill •«*«««*«»#*»»«» MESSAGE BUFFER*"* ***"***»***«**»* 

« ARBITRARILY SET AT 2560 BYTES (256 BYTES PER HSG 
* PLUS HSGS PLUS 1 TERMINATOR). 



Figure 2-5. EQU Use Example 2 
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Operators and Expressions 

EDTASM allows a limited number of operations involving 
addition, subtraction, ANDing, and shifting. These oper- 
ations are performed by the operators +, — , &, and <. 
Addition of constants are shown in Figure 2-6, along with 
one subtraction example for the size of FTAB. Expressions 
may also include a mixture of numeric data and labels in 
any combination. 







01130 


; 














01140 


; FUNCTION TABLE 












01150 












80BE 


CI 


01160 


FTAB 


DEFB 


"D'+80H 


DEFINE MESSAGE 




80BF 


D3 


01170 




DEFB 


•S'+80H 


DEFINE SPEED 




80C0 


D2 


01 180 




DEFB 


'R'+80H 


TRANSMIT RANDOM 




80C1 


B0 


01190 




DEFB 


'0**80H 


TRANSMIT MESSAGE 





80C2 


B1 


01200 




DEFB 


' 1 '*80H 




1 


80C3 


B2 


01210 




DEFB 


>2'+80H 




2 


80C4 


B3 


01220 




DEFB 


'3'*80H 




3 


80C5 


B4 


01230 




DEFB 


'4 >*80H 




4 


80C6 


B5 


01240 




DEFB 


'5'+80H 




5 


80C7 


B6 


01250 




DEFB 


■6'+80H 




6 


80C8 


BT 


01260 




DEFB 


•7'+80H 




7 


80C9 


B8 


01270 




DEFB 


'8'+80H 




8 


80CA 


B9 


01280 




DEFB 


'9'+80H 




9 


80CB 


DO 


01290 




DEFB 


'P'+80H 


SET PRINT 




80CC 


CE 


01300 




DEFB 


'II ' + 80H 


RESET PRINT 




000F 




01310 


FTABS 


EQU 


$-FTAB 


SIZE OF FUNCTION 


TABLE 


0000 




01320 




END 








00000 TOTAL 


ERRORS 













Figure 2-6. Operators and Expressions 



Using EDTASM to Edit and Assemble Programs 

EDTASM is geared to editing and assembling one module 
of assembly-language code. After you have specified, flow- 
charted or analyzed, and coded a program on paper, use 
the Editor in EDTASM to enter the complete program code. 
Although you have probably divided the program into a 
number of different functional modules, include the 
modules as one large, whole assembly-language source 
file. 
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Hints and Kinks 2-4- 



Typical Assembly Sequence 

With the source file in memory (either from 
cassette or from keyboard entry) , a typical 
assembly sequence might be: 

1. *A/N0/WE Assemble to screen with no 
object; wait on errors, 

2. Go back to Editor to correct any errors. 
When there are no errors, go to 3. 

3. *A/N0/LP Assemble to line printer with no 
object . 

4. Take the listing and do a comprehensive 
desk check (Coffee or other stimulants 
allowed, ) 

5. Repeat steps 1 through 4 as often as 
required, 

6. *A NAME/LP Assemble final assembly to line 
printer, object to cassette with name 
"NAME" , 

7. Debug. 



The resulting source file on cassette is then assembled as 
one large assembly. MORG, the Morse Code Program of 
Chapter 13, is a large program that approaches the limits 
of memory capacity. Because all of the source lines must 
be held in memory at one time, in addition to the symbol 
table, there's a practical limit to the size of the program 
that can be assembled under EDTASM. This limit depends 
upon the memory size of the system, number of characters 
in the source file, and number of labels used. We'll see in 
the next chapter how you can use the Disk Assembler to 
overcome some of the limitations by using a different 
approach to assembling and loading programs, but let's 
first get a clear understanding of EDTASM operation. 
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As we can see from looking at MORG, the entire program is 
assembled in one swell foop. The ORG statement specifies 
the starting address of the program, and all instructions 
are referenced to the assembler location counter. The 
assembler location counter is initially set by ORG and 
incremented as each instruction or pseudo-op is generated. 
EDTASM produces object code for the program as a cas- 
sette file. The object code is very similar to the machine 
code shown on the listing, but contains some additional 
data to hold the file name, origin, number of bytes per 
record, checksum, etc. 

You can load the resulting object code by a SYSTEM 
command while in Level II BASIC monitor mode. The 
SYSTEM command enables you to load the object file 
created under EDTASM and then to transfer control to the 
starting address of the program (specified by the operand 
used with the END pseudo-op). 

The object code produced by EDTASM generally can be 
loaded and executed only at one point in memory, the area 
at which it was ORiGined. If you load the object code at 
another area (by some devious means), it won't execute 
properly. Let's see why this is so. 

Relocatability 

Instructions in the Z-80 instruction set are generally 
relocatable or non-relocatable. Relocatable instructions 
will execute properly anywhere in memory; non-relo- 
catable instructions contain absolute references and will 
execute only in the area for which they were assembled. 



50 



■ Hints and Kinks 2-5 



Why All the Interest in Relocatability? 

Much Z-80 literature talks about the 
relocatable instructions or code and touts the 
advantages. Are there many advantages in the 
relocatable Z-80 instructions? 

Not really. Any large piece of code is 
probably not relocatable because it will have 
to contain JPs and CALLs — unless some pretty 
clever coding is done. About the only reason 
for relocatability on the TRS-80 is to allow 
short code segments to be embedded in BASIC 
programs, This merges BASIC and 
assembly-language code and allows the 
programmer to use assembly-language code to 
speed up his time critical processing. 

Occasionally someone will try to take an 
existing program that is available in machine 
language only (no listing) and attempt to 
relocate it to run elsewhere. This is 
possible, but very tedious. Try it only on a 
favorable bio-rhythm day! 



Figure 2-7 shows typical code for the MORG program 
produced by EDTASM. Let's take a look at the instructions 
to see which are relocatable, which are not, and why. 



NOT RELOCATABLE 
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6197 CDFB83 02310 SPE005 CALL CLRCOM ;CLEAR COMMUNICATION AREA 

819* 21CB86 02350 LD HL.MSG1 iSPEED MESSAGE 

81 9D 01103F 02300 LD BC.LINE13 ;LIHE 13 

81A0 CD6D83 02370 CALL DSPMES ;DISPLAY SPEED MESSAGE 

81A3 0602 023B0 LD B,2 ;2 CHARS 

81A5 CD0L81 02390 CALL INPUTS ;GET CHARACTER STRING 

81A8 2035 02100 JR NZ.SPE020 ;G0 IF GT 2 CHARACTERS 

81AA CD9085 02110 CALL DECBIN ; CONVERT TO BINARY 

81AD 2030 02120 JR NZ.SPE020 ;G0 IF ERROR 

81AF 7D 02130 LD A,L ;GET SPEED 0-99 

81B0 FE03 02110 CP 3 ;TEST FOR 3 HPM 

81B2 FADF81 02150 JP M.SPE020 ;G0 IF LT 3 HPM 

81B5 FE3D 02160 ^Ct _ 61 i TEST FOR 60 HPM 

81B7 F2DF81 02170 #JP P.SPE020 ;GO IF GT 60 HPM 

81BA 21C003 02180 / LD HL.SPEEDF ; 1 200/ W'PM= DOTO TIME 

81BD IF 02190 / LD C,A ;WPH LS BjTE 

81BE 0600 02500 / LD B,0 ;N0W IN BC 

81C0 11FFFF 02510 / LD DE,-1 :QU0TIENT 

RELOCATABLE 

Figure 2-7. Relocatable Code 
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The CP Gi found 12 lines after SPE00 5 has 
machine-language code of FE3D. By reference to Appendix 
II, we can see that the first byte of this instruction is the 
op-code and that the second byte is the data value of 61 
(3DH). This instruction would assemble exactly the same 
way at any spot in memory, because the op-code is fixed 
and the data value would have to be the same. 

The instruction CALL CLRCOM, however, is a different 
beastie. CLRCOM is a subroutine that appears somewhat 
later in the program. If you'll look again at the formats in 
Appendix II, you'll see that a CALL consists of three bytes. 
The first of these is an op-code of CDH. The second and 
third bytes are an absolute memory address that hold 
the call address with the bytes in reverse order. The 
address in this case is that of CLRCOM, which is at 83FBH. 
Would this instruction execute properly if MORG were 
moved to another area of memory? Obviously not, as the 
CLRCOM subroutine would also be relocated, and its 
address would be other than 83FBH. A similar situation 
would exist for instructions such as JP BPE0 20, 
LD HL >MSG4, and others that contain absolute addresses. 

You might be wondering if it's possible to write programs 
in pure relocatable code. As a matter of fact, you can 
write relocatable code in relatively short routines that 
contain no absolute addresses and use JR type jumps for 
conditional and unconditional jumps. We'll explore some of 
the techniques in Chapter 5. Longer programs require you 
to do something such as reassembling your program by 
EDTASM with a new Origin. Another way is to use the 
facilities of the Disk Assembler. We'll look into this last 
method in the next chapter. 
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Chapter Three 

Assemblers and Assembling — 

Disk Assembler 

In this chapter we'll talk about the Radio Shack Disk 
Assembler. You should use this material only as a sup- 
plement to the Disk Assembler User Instruction Manual, 
since an adequate discussion of the Assembler would 
require more than just a single chapter. A good example 
for some of the techniques associated with the Assembler 
is included in Chapter 14 where we illustrate an entire 
program made up of modules assembled and loaded by the 
Disk Assembler and Loader. We'll be using further exam- 
ples in the text of Disk Assembler code and EDTASM code 
in the remaining chapters of this book. 

Comparison Between EDTASM 
and the Disk Assembler 

Although EDTASM is cassette-based and the Disk Assem- 
bler must use files from disk, the two systems share more 
similarities than differences. Both edit assembly-language 
source files and have approximately the same 
line-oriented type of Editor with very similar commands 
and subcommands. Both assemble the source files and look 
for identical formats as far as Z-80 mnemonics and 
instruction syntax. Both use pseudo-ops for origin; 
pseudo-ops for definition of bytes, words, text, and storage; 
and a pseudo-op for equates. Many EDTASM source files can 
be converted to Disk Assembler use quite easily with a 
minimum of editing changes, primarily by adding a colon 
after each label and changing some of the data definitions. 
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Hints and Kinks 3-1 



Format Differences between 
EDTASM and Disk Assembler 

There are several format and pseudo-op 
differences between the two assemblers, The 
most obvious is the use of a colon after 
labels on most source lines (not on an EQU) , 

The pseudo-ops for data definition are also 
somewhat different. Although DEFB , DEFW, DEFS 
and DEFM may be used, the Disk Assembler also 
uses DB in place of DEFB, DW in place of DEFW, 
DS in place of DEFS. and DC in place of DEFM. 
DB 'string' can also be used as a DEFS. 

Multiple arguments can be used for the data 
definition pseudo-ops as in "DEFB 2,3.5" . 

The Disk Assembler also requires at least a 95 
character wide line for assembly listing. 

Can you convert EDTASM files on cassette to 
Disk Assembler source files? Conceivably, a 
short assembly-language conversion program 
might be used that would convert the format 
differences above (and others). It would make 
a nice exercise . , , 



The simple uses of the Disk Assembler look very similar to 
EDTASM. However, when all the capabilities of the Disk 
Assembler are utilized, there are some major advantages 
to the Disk Assembler not found in EDTASM. In approxi- 
mate order of importance, these are: 

1. The Disk Assembler uses disk files for source, 
object, and listing. 

2. The Disk Assembler produces object-file output in 
the form of relocatable object modules which 
are loaded by a special Loader. 

3. The Disk Assembler has a macro capability to 
generate in-line macro code. 

4. The Disk Assembler has a number of pseudo-ops 
relating to program sections and conditional 
assembly. 
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5. The Disk Assembler has a number of pseudo-ops 
relating to listing format. 

We'll discuss each of these points in the following text, and 
give a number of examples to illustrate each concept. 

Disk Files for the Disk Assembler 

The Disk Assembler operates on assembly-language 
source files on disk created by the Editor portion of the 
software package. These source files are processed by the 
Assembler and the resulting object files are output to disk. 
The object files can be loaded into memory by the Loader 
portion of the package, and a CMD (CoMmanD) file can 
then be dumped to disk. 

The CMD file, is a core-image file of the machine- 
language code that makes up the complete assembly- 
language program. It can be loaded and executed by 
simply typing in the name of the CMD file after the TRSDOS 
"DOS READY" prompt. 

In addition to the source, object, and CMD files created by 
the Editor and Assembler, a listing file can be created for 
a hardcopy listing. The listing file can then be "PRINTed" 
on the TRS-80 system line printer. 

Using the Editor for Source Files 

The assembly-language source file is similar to other files, 
but there are significant differences. The assembly-lan- 
guage source file created by the Editor is almost an ASCII 
file. However, there is some non-ASCII coding for the line 
numbers at the start of each line. The Editor commands 
are similar to the Editor commands in Level II BASIC or 
EDTASM, with some differences. The symbol "." is used to 
refer to the current line and the symbol "*" refers to the 
last line of the edit buffer, just as in the other editors. 
The first line of the buffer, however, is signified by 
the symbol, "-•■" (up arrow), rather than "#". 

Ranges of lines may be specified, just as in the other 
editors. For example, to delete lines 200 through 300, give 
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the Editor command D200:300. A new type of range 
specification, however, deletes a specified line through the 
next n lines. D200 ! 3, for instance, would delete line 200 
and the next 3 lines following line 200. 

The Editor commands — I (Insert), D (Delete), R (Replace), 
P (Print), and N (Number) — all operate the same as in the 
other editors. To edit a specific line, though, the command 
A (Alter), rather than E is given. See Table 3-1. 

Table 3-t 
Disk Editor/Assembler Edit Commands 



imar 

A 
B 
D 
E 


id Action 

Alter 
Begin 
Delete line 
Exit Editor 


F 


Find 


I 


Insert 


K 

L 


Kill 
List 


M 


Mark 


N 


Number 


P 

R 
S 


Print 
Quit 
Replace 
Substitute 


W 


Write to disk 


X 


Extend 



Typical Example* 

A 100 starts edit (Alter) of line 100 
B / 2 moves to beginning of page 2 
D 100 s 200 deletes lines 100-200 
E NAME/MAC exits Editor, writes 

file NAME 
F100;200$TWINE$ finds string 

"TWINE" 
1 1 00 # 1 inserts lines from 100, 

increment 10 
K / 2 kills page mark at page 2 
L100:* prints lines from 100 through 

end 
M 1 00 inserts page mark after 

line 100 
N 1 00 > 1 renumbers lines from 100, 

increment of 10 
P 1 00 : 200 displays lines 100-200 
quits Editor without disk write 
R100 replaces line 100 
S100;200$MOD II$M0D 111$ 

substitutes "MOD III" 
w NAME /MAC writes text as disk file 

"NAME/MAC" 
X 1 00 : 200 enters extend mode for 

lines 100-200 



f 



*Consult Disk Editor/Assembler manual for the many variations. 
$ = BREAK 
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Editor subcommands, commands that operate within a 
specified line, are very similar to the other editors. You'll 
discover some new subcommands in this mode, though. 
See Table 3-2 for a complete list. 

Table 3-2 
Disk Editor/Assembler Edit Subcommands 



Subcommand 


Action 


"Usual" Form * 


A 


Prints remainder, enters changes, 
concludes editing 


A 


B(lanks) 


Inserts spaces 


B or iB 


C(hange) 


Replaces characters 


C <ch> or iC <texf> 


D(elete) 


Deletes characters 


D or iD 


E(nter) 


Enters changes, concludes editing 


E 


F(ind) 


Finds text 


F$<fexf>$ 




Inserts characters 


G<ch> 


H(acks) 


Delete remainder and enter Insert 
mode 


H or H<fexr>$ 


I(nsert) 


Inserts text 


I or Kfexf>$ 


K(ill) 


Kills characters up to <ch> 


K<ch> 


L(ine) 


Prints line, positions cursor to 
beginning 


L 


IM(ot) 


Restores line, moves to next line 


N 


O(bliterate) 


Deletes all characters up to 
<fexf> 


0<fexf>$ 


P(osition) 


Prints remainder of line, cursor 
static 


P 


O(uit) 


Exits edit mode and restores 
original line 





R(eplace) 


Replaces characters with <fexf> 


iR<fexf>$ 


S(earch) 


Finds character <ch> 


S<Ch> 


T(runcate) 


Deletes remainder of line and 
concludes edit 


T 


W(ord) 


Moves the cursor to beginning of 
next word 


N 


(e)K(tend) 


Print remainder of line, go into 
Insert mode 


" 


Z(aps) 


Deletes word 


Z 


© 


Delete character 


© 


(ENTER) 


Prints remainder, enters changes, 

concludes edit 
Restores original line, repositions 


(ENTER) 


(SHIFT)© 


(SHIFT)© 




cursor to beginning 
Spaces over character 




(SPACE) 


(SPACE) 


© 


Moves cursor to line end 


© 



i = number 

$ = BREAK or ENTER 

<ch> = character 

<fexf> = text string 

* Consult Disk Editor/Assembler manual for the many variations 
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Here's the procedure for creating a new source file: 

1. Load the Editor by entering EDIT after the 
TRSDOS READY prompt. The Editor will be loaded 
as a CMD file and will start execution. 

2. The Editor will ask for the file name by displaying 
FILE;. 

3. Enter a TRSDOS file name with optional extension, 
password, and drive number; follow that with the 
BREAK key. Since the Assembler works with the 
extension /MAC, this would be the best choice for 
the extension. You can also disregard passwords, 
unless you're really paranoid about your source 
files! Some examples of source file names might be 
MTALBMAC:1 or HTPM/MAC. 

4. You'll now be at the command level, as indicated 
by an asterisk (*), and can start creation of source 
lines by insert commands such as 1 1 00. 

To modify an existing source file, follow a similar sequence 
to the one above, only type an ENTER rather than a BREAK 
after the file name. 

During the source file editing, you can P(rint) the assem- 
bly source lines on the screen, or get a hardcopy on your 
system line printer by the L(ist) command. During the 
editing session, you will notice some disk activity taking 
place. The Editor will be reading in pages for the source 
file as required. 

When you have the source file the way you'd like it, you 
can write a new source file to the disk by giving the E(nd) 
command and the name initially used. If this is modifi- 
cation of an existing file, the form of the command is 
E NAME/MAC, where the NAME of the source file must be 
different than the one originally read in. 

This last point means that when you edit an existing file, 
you must first read in the old file, perform editing on the 
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old file, create a new file at the end of the edit session, 
KILL the old file name under TRSDOS, and then RENAME 
the new file name to the old name to get back to square 
one. Though somewhat tedious, this goes quite rapidly and 
does offer some automatic protection against clobbering 
an old file before its time. 



Hints and Kinks 3-2 1 

Typical Edit, Rename Sequence 


Here's a typical Edit and 


rename sequence: 


DOS READY 




EDIT 


Load Editor 


FILE; EQUATE/MAC 


Read in old file 


(title, copyright) 




*A100 


Edit line 100 


00100 TITLE EQUATE 




*E EQUATE1/MAC 


End edit, write out 


DOS READY 




KILL EQUATE/MAC 


Kill old file 


DOS READY 




RENAME EQUATE 1/MAC TO 


Rename new to old 


EQUATE/MAC 


name 


DOS READY 





Relocatable Object File Assembly 

The Assembler will read in the source file created by the 
Editor, assemble it, and produce a relocatable object file, 
a listing file, or both on disk. We need to talk about the 
relocatable object file, since the philosophy here is quite 
different from the EDTASM approach. 

Figure 3-1 shows a typical assembly listing for the Disk 
Assembler. (This is a module of the Tic-Tac-Toe Artificial 
Intelligence Program of Chapter 14.) The appearance of 
this assembly is very similar to what EDTASM would 
produce. The source line image and the edit line number 
portion are almost identical. 
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Looking at the machine language code produced by the 
Assembler, we see that many of the instructions look 
familiar. ADD IX >BC, for example, generates two bytes of 
DD 09, just as it would in EDTASM. If you look at some of 
the CALLs, however, you'll notice that the address of the 
CALL is zeroes. Also, the address for JP instructions (not 
shown) appear to be low-valued, such as 0029. Note also 
that 16-bit values are printed in "normal" order on the 
listing; in memory they are still least significant byte 
followed by most significant byte. What's the logic behind 
these differences? 

In a relocatable object module containing the machine- 
language code for this assembly, the machine-language 
code is referenced to the start of the module. The location 
column on the listing starts at location 0' (the prime 
indicates that the code is relocatable). Jumps within the 
module generate instructions that contain addresses that 
are "displacement" addresses from the start of the module. 

The Loader for the Disk Assembler handles the task of 
loading in a number of these relocatable object modules 
and of filling in the proper addresses for non-relocatable 
instructions such as JPs and CALLs. 



Hints and Kinks 3-3 

Mode Indicators 

The character at the end of the location value 

is the mode indicator as follows: 

' Code relative 

" Data relative 

! Common relative 

(space) Absolute 

* External 

These characters are also used after two-byte 
values . 
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Another thing that the Loader does is to link together 
locations from module to module. Obviously there has to 
be some way for modules to communicate with one 
another. For example, a portion of main code, such as is 
shown in Figure 3-1, might have to call a subroutine 
represented by another module. 

The loader does this by linking together EXT(ernals) and 
ENTRYs from module to module. The ENTRY operand is a 
location within one module that might be referenced by 
code in another module, as for a CALL or JP. The EXT 
operand is a label that is external to the module but is 
referenced inside the module. 

Look again at Figure 3-1. At location 14' a CALL is made 
to a subroutine DSPMEB. This subroutine is external to this 
module and declared as an EXT in the pseudo-ops at the 
start of the program. Location ART IP, however, is the 
main entry point and is declared as an ENTRY. Note that 
the CALL to DSPMES results in machine code of CD 0000*. 
The address will be filled in by the loader at load time. 

A complete assembly-language program is created by link 
loading a group of relocatable modules, such as the one 
related to the listing in Figure 3-1. The loader compiles a 
table of all the EXT and ENTRY points, somewhat 
analogous to the Assembler symbol table, and eventually 
goes through a "threaded list" to fill in the addresses for 
every externally referenced (or global) label. Labels 
within the module (local labels) are, of course, no problem. 

There are several major advantages to this type of assem- 
ble and load scheme: (1) we are no longer limited by 
memory size in constructing large assembly-language 
packages; (2) we don't have to worry about relocation as 
the loader takes care of that automatically; and (3) the 
assembly-language design job can be more structured by 
dividing the design into a number of separate modules (an 
especially valuable feature when more than one pro- 
grammer is working on a project). 
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There are a few minor disadvantages. For one thing, the 
entire edit, assemble, load process is less interactive and 
more time consuming. It does take somewhat more time to 
generate a new assembly-language package as the entire 
load process has to be repeated, even if only one line has 
been changed. However, the extra time spent is a small 
price to pay for the increased flexibility of the Assembler. 

Macro Capability 

Another feature the Disk Assembler has over EDTASM is 
the ability to use macros. Macros are essentially in-line 
subroutines generated at assembly-time. For example, 
suppose that we have six instructions that appear a dozen 
times in an assembly-language program: 

ADD HL#HL iVALUE*2 

PUSH HL 5 SAME VALUE*2 

ADD HLtHL iVALUE*4 

ADD HL>HL 5MALUE*8 

POP DE 5VALUE*2 

ADD HL>DE ?UALUE*10 

Every time we wanted to perform these six instructions, 
we'd have to key them in to the edit. Of course, one 
alternative would be to include them as a subroutine, but 
another way would be as a macro. 

Figure 3-2 shows the six instructions defined as a macro 
by a macro definition, and later invoked as a macro by a 
macro call. The macro definition involved the pseudo-op 
MACRO, which defined the label MUL 1 as the macro name, 
and EN DM as the pseudo-op which ended the definition. 
After the definition, any use of the macro name in the 
op-code column would automatically generate a macro 
expansion for the six instructions. You can use the macro 
as many times as needed. 
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3E 23 



0002' 


29 


0003 ' 


E5 


0001 ' 


29 


0005' 


29 


0006 • 


D1 


0007 ' 


19 



00100 


; SAMPLE MACRO 


JSE 




001 10 


; FIRST 


DEFINE 


THE MACRO 




00120 


MUL10 


MACRO 






00130 




ADD 


HL.HL 




00110 




PUSH 


HL 




00150 




ADD 


HL.Hl 




00160 




ADD 


HL.HL 




00170 




POP 


DE 




00180 




ADD 


HL.DE 




00190 
00200 


EN DM 
; NOW THE MACRO 


CAN BE INVOKED 


AS REQUIRED 


00210 


START: 


LD 


A.23H 


;BLAH, BLAI 


00220 
00230 


ADD 

PUSH 

ADD 

ADD 

POP 

ADD 


MUL10 

HL.HL 

HL 

HL.HL 

HL.HL 

DE 

HL.DE 

END 




; INVOKE 



Figure 3-2. Simple Macro Use 

Such macro use does have certain advantages as well as 
disadvantages. By defining the six instructions as a macro, 
we've made it much easier to generate the code simply by 
a macro call in the op-code. The code generated is also 
somewhat faster than the equivalent subroutine would be, 
since the overhead of the CALL and RET is gone. On the 
other hand, we've used up quite a bit more memory than 
the corresponding subroutine. 

If this were the extent of macro capability, you might be 
tempted to forget the whole thing. However, you can use 
macros with arguments to generate tailored code to fit 
the generalized case. 

An example of such a macro is shown in Figure 3-3. This 
macro will take a given character and fill a screen line 
with it. The macro definition consists of the macro name 
and MACRO pseudo-op as before, but it also has two 
dummy arguments, CHAR and LINENO, representing the 
character and the line number, 0-15, to be used. 



00100 
00110 
00120 

00130 

00110 
00150 
00160 
00170 
00180 
00190 
00200 
00210 
00220 



THIS IS A SAMPLE MACRO WITH ARGUMENTS 

FIRST DEFINE THE MACRO WITH DUMMY ARGUMENTS 



MACRO CHAR, LINENO 



'LOCAL """"LOOP «*- 
LI' A, CHAT-. 

LD HL,3COOH+LINENO»61 

LD B,61 

(HL),A 

HL 

LOOP 



• THIS PREVENTS DUPLICATE 
LABELS WHEN MACRO 
IS EXPANDED 



OOP; LD 
INC 
DJNZ 
EN DM 
NEXT, INVOKE THE MACRO WITH REAL ARGUMENTS 
FILL ' ',0 
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0000' 


3E 


20 


0002 ' 


21 


3C00 


0005 ' 


06 


10 


0007 ' 


77 




0008 ' 


23 




0009 ' 


10 


FC 


000B' 


3E 


2A 


OOOD' 


21 


3C40 


0010 ' 


06 


40 


0012' 


77 




0013 ' 


23 




oon • 


10 


FC 


0016 ' 


3E 


88 


0018' 


21 


3C80 


001B' 


06 


40 


001D' 


77 




001E' 


23 




001F' 


10 


FC 





LD 


A, ' ' 


V 




LD 


HL,3C00H+0«64 






LD 


B,64 




..0000: 


LD 


(HL),A 


I EXPANSION 1 




INC 


HL 






DJNZ 


.0000 


1 


00230 




FILL '«',1 


k 




LD 


A, •»' 






LD 


HL,3CO0H+1«64 






LD 


B,64 


> EXPANSION 2 


. .0001 : 


LD 


(HL),A 






INC 


HL 






DJNZ 


.0001 


1 


00240 




FILL 88H,2' 






LD 


A.88H 






LD 


HL,3C00H+2»64 






LD 


B,64 


■ EXPANSION 3 


. .0002: 


LD 


!HL) ,A 






INC 


HL 






DJNZ 


.0002 

END 




00250 







Figure 3-3. Macro Use With Arguments 

The arguments are called dummies because they only 
serve to denote when you are to use "real" arguments 
when the macro is called. When the macro is invoked, as 
shown in the listing, "real" arguments replace the dummy 
arguments, and specialized code is generated with the real 
arguments put in the proper places in the code. Any 
number of dummy arguments can be used in a macro, 
subject only to line length. 

It is not hard to see how to create macros to define an 
entire applications language. The resulting code for the 
application could consist primarily of macro calls, allowing 
quick development time but at the expense of memory. 
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More Complicated Macros 

The macros used as examples in the text are 
quite straightforward. The Disk Assembler, 
though, has a number of macro operators, 
conditional assembly pseudo-ops, and rules for 
macro definition and use that may be used to 
construct very powerful macros. Such things as 
a NUL operator, to test for a null argument, 
EXITM, to terminate a macro before a complete 
expansion, and SET, to permit redefinition of 
a variable name are but a few of the functions 
that can be used to create truly horrendous 
code ! 
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Pseudo-Ops For Program Sections 
and Conditional Assembly 

The Disk Assembler adds a number of new pseudo-ops 
other than those for EXT(ernals), ENTRYs, and macros. 
Some of these are related to program sections and some 

to conditional assembly. 

Program Sections 

The pseudo-ops ASEG, DSEG, and CSEG are related to 
program sections. The Disk Assembler is initialized in 
the "relocatable" mode; any code produced in this mode is 
relocatable and can be modified by the loader at load time 
to run wherever it is being loaded. 

If the ASEG pseudo-op is used, however, all code following 
will be in absolute mode. It will be assembled to run at 
one specific area in memory. The ASEG is normally 
followed by an ORG (Origin) to define the area of memory 
at which the code is to be assembled. 

ASEG ?SET ABSOLUTE 

ORG 8000H iSTART OF ABSOLUTE AREA 

The CSEG pseudo-op defines a code relative section of the 
program. This is the relocatable code section. CSEG is not 
required unless an ASEG has been used, in which case you 
should use a CSEG to force the Assembler back into its 
default mode. You can intermix ASEGs and CSEGs as 
needed. 

The third pseudo-op of this type is the DSEG, or data 
relative segment definition. Here again, DSEG should be 
followed by an ORG to define where the data is to go. The 
DSEG could be used, for example, to include all variables 
and working storage in each program module in a separate 
data-segment area of memory for convenience in debug- 
ging. 

Essentially, the Disk Assembler maintains three separate 
location counters — one for the absolute, one for the code 
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relative, and one for the data relative sections of memory. 
An example is shown in Figure 3-4, where the three types 
of program sections are used with relative impunity. 
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Conditional Assembly 

Another set of pseudo-ops are concerned with conditional 
assembly. Conditional assembly refers to a segment of 
code that is either assembled or not assembled according 
to some defined condition. Conditional assembly might be 
used, for example, by a company that has many versions of 
a software program. One segment of code might be neces- 
sary if a user has a disk system, while another might be 
necessary if the user has cassette. The section for a disk 
system might appear as follows: 

5ASSEMBLE THIS CODE FOR DISK 

IF DISK 5DISK FLAG 

DISKC LD A *5 5L0AD FLAG 



ENDIF 

If variable DISK is not zero, this code will be assembled. If 
DISK = 0, the code will not be assembled. The dots indicate 
additional code in the segment. There are a number of 
conditional assembly pseudo-ops including the REPT 
("repeat n times") and IRP pseudo-ops. For information on 
the rest, consult the Disk Assembler Programming Man- 
ual. 
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Hints and Kinks 3-5 

Elegant Pseudo-Ops 

There are a number of pseudo-ops we 
haven't talked about here, such as SET, 
which allows an assembly time variable to 
be redefined, REPT, which allows a block 
of statements to be repeated n times; and 
LOCAL, which defines a local label within 
a macro . 

In my opinion, most assembly-language 
programmers probably won't exercise the 
full capabilities of the Disk Assembler by 
using such ''elegant' 1 operations. The 
last time I used an elaborate scheme to 
have the assembler generate a large 
complicated table of data, I was awakened 
at 2:00 a.m. by a call from the computer 
operator. The operator informed me that my 
(200-line) assembly had been assembling 
for 4 hours and asked if it was 
1 ' normal ' ' ! 



Pseudo-Ops for Listing Format 

There are a number of pseudo-ops in the Disk Assembler 
that make listings "prettier." TITLE specifies a title to be 
used on each page of the listing. SUBTTL allows the user to 
specify a subtitle. PAGE causes a "page eject" to start the 
listing on a new page; this is handy for isolating logically 
different sections of code. .COMMENT may be used in place 
of comment lines starting with a semicolon. The first 
character of the following text is used as a delimiter and 
the following text is used as a comment block until the 
same character is encountered. 

Several other pseudo-ops control listing output, macro 
listing output, and cross-reference listing output. See the 
Disk Assembler manual for details. 
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Using the Disk Assembler 

After you have used the Editor to create assembly- 
language source modules, the Assembler reads in a source 
module from disk, assembles the code, and optionally 
produces a relocatable object module and listing file. 

The format for the assembly command is — 

#NAME1 »NAME2=NAME3 
* fNAME2 = NAME3 
*NAME1 f = NAME3 or 
*=NAME3 

In case this format's confusing (I found it so), we'll 
interpret for you. The first command assembles source file, 
NAME3, from disk and produces a relocatable object file, 
NAMEl, and a listing file, NAME2, on disk. The listing file 
may be listed by a PRINT command. 

The second command does not produce a relocatable 
object-file. The third command does not produce a listing 
file. The fourth command produces neither a relocatable 
object file nor a listing file (handy for assembly error 
checks). 

The names may actually be the same for all three. If a 
source file is on disk called NAME/MAC, the command 

#NAME »NAME = NAME 

produces a relocatable object file called NAME/REL and a 
listing file called NAME/LST. The file extensions are 
automatically generated by the assembler. Of course, you 
can also use passwords (ugh!) or disk drive numbers. 
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Hints and Kinks 3-6 

CREF 




We haven't mentioned the cross 


reference 


facility of the Editor/Assembl 


sr at all . 


It's not that it isn't useful, 


but it does 


create another step in the assembly 


process, You must set the CREF 


switch 


during assembly by an assembler command 


such as *TEST »TEST/C = TEST , The resulting 


listing file has ' 'hooks' ' in i 


.t that 


enable processing by CREF, The 


result is 


an alphabetized listing of the 


variable 


names along with line numbers c 


f lines in 


which each is referenced or defined. Use 


at your option , 





Loading the Object Modules to Produce a 
Command File 

Let's assume we've gone through the assembly process for 
the three modules shown in Figure 3-5. They make up a 
horrendously complicated program to clear the screen, 
print a title, read a key of 0-7, and output the key to the 
center of the screen. Three modules were used here so we 
could illustrate the linkages between the modules at load 
time. 
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The modules are out on disk as MAIN, PRINT, and READ and 
emulate the usual arrangement of modules produced while 
using the Disk Assembler. The main portion of code calls 
the other modules as subroutines. There could also be 
ENTRY points in MAIN or EXTernals in PRINT and READ if 
this were more complicated code. 

The Loader is entered by typing L80 after the TRSDOS 
prompt, TRSDOS READY. The chief commands to consider 
in the Loader are the -P command, the -N command, and 
the -E command. The -P command has the form -P-.XXXX. It 
sets the loader location counter to location XXXX. The -N 
command has the form NAME-N. It establishes a name for 
the command file. The -E command ends the edit, outputs 
the linked relocatable modules to the disk as command 
(/CMD) file NAME, and ends the edit. 

The load sequence of commands is shown in Figure 3-6. 
The load location counter is first set to 8000H by a -P 
command. The three modules are then loaded by typing in 
each name. Finally, the linked modules are output to disk 
as TEST/CMD, and the load is ended. TEST can now be 
loaded and executed from TRSDOS by simply typing TEST. 



*-P:8000 






*MAIN 






DATA 


B000 


8018 


PRINT* 


801 i 


READ* 


*PRINT 






DATA 


8000 


802C 


READ* 


8014 




*READ 






DATA 


8000 


803F 


*TEST-N, - 


-E 




(0000 


803F) 




DOS READY 







B014 



SET LOAD ADDRESS 
LOAD MAIN MODULE 
SIZE OF CURRENT DATA 
UNRESOLVED EXTERNS 
LOAD PRINT MODULE 
SIZE OF CURRENT DATA 
UNRESOLVED EXTERNS 
LOAD READ MODULE 
SIZE OF CURRENT DATA 
FILE NAME "TEST". END 



Figure 3-6. Typical Load Commands 
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Figure 3-6 also shows the loader symbol table displayed 
after each load. This lists all unresolved symbols in 
addition to the memory area loaded. At the end of the load, 
all externals should have been resolved, or a load error 
will result. If any external is unsatisfied, it means that a 
module referenced an external name by an EXTern, and 
there was no corresponding ENTRY point. This may mean 
that you did not load the module containing the name, or 
that you didn't declare the name in an ENTRY. Either 
condition is an error. 

The procedure above is the loading process in microcosm 
for any size assembly-language program. The Tic-Tac-Toe 
program in Chapter 14 uses 25 separate modules with a 
large number of ENTRY points, yet the procedure is vir- 
tually identical. 

The "core image" of the three modules above is shown in 
Figure 3-7. All addresses have been satisfied during the 
load process, and the program appears as one contiguous 
program block. 



. START OF MAIN 

PRINT ADDRESS i 



READ ADDRESS 



END OF MAIN 
START OF PRINT 



B000 
8010 



21 00 3C/11 00 10/3E 20_F77 23 B7 EO 52 19 20 F8 

CD 18 60/ CD 2C 80/ 18 FEj[2 1 00 3C 1 1 26 80 14 B7 

020 -C8 77 23 13 18 F8 51 19 51 1C 15 00T.3A 10 38 B7 

030 28 FA 06 FF 01 OF 30 FC 78 C6 30 32J20 3E C9JFE 



END OF PRINT 
START OF READ 



END OF 
READ 



Figure 3-7. Core Image Module 
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Chapter Four 

Loading, Executing, and Debugging 
Assembly-Language Programs 

Up to this point we've talked about general considerations 
in producing programs using EDTASM and the Disk 
Assembler — how to edit, assemble, and list source files. 
We'll move on to discuss the next step, loading and 
executing the resulting object code. You can run 
assembly-language programs as "stand-alone" programs or 
interface them to BASIC programs. This chapter describes 
both methods. We also cover "debugger" programs and 
some tricks in debugging techniques. In short, we're going 
to talk about the subject, "Now that I have the assembled 
program, what do I do with it?" 

EDTASM System Tapes 

The result of an edit and assembly using EDTASM is a 
SYSTEM file on cassette. A SYSTEM file resembles the 
machine-language code seen on the EDTASM listing. It 
contains other data, however, to enable the Level II BASIC 
interpreter to load the machine-language code into the 
proper place in memory and verify the data as correct. The 
format for SYSTEM tapes is shown in Figure 4-1. 
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255 BYTES 
OF ZEROES 



SYNC BYTE = A5H 



55H 



FILE NAME IN 
ASCII PADDED TO ^ 
6 BYTES W/BLANKS 



3CH 



# BYTES IN RECORD 



LOAD ADDRESS 



MACHINE-LANGUAGE 
BYTES : 



CHECKSUM 



78H 



ENTRY POINT 
ADDRESS 



FIRST "LOGICAL" HECOBD 



SECOND AND Nth LOGICAL 
RECORDS 



. OTHER POSSIBLE 
"PHYSICAL" RECORDS 
EACH WITH ZEROES. 
SYNC BYTE 



LAST LOGICAL RECORD 



Figure 4-1. SYSTEM Tape Format 

A string of 255 zeroes are at the beginning of the cassette 
file, followed by a sync byte of A5H. The sync byte 
synchronizes the cassette tape driver of the BASIC inter- 
preter — informing it that the next byte will be valid data. 
The zeroes and sync byte precede each physical record on 
the SYSTEM tape. A SYSTEM tape may have one or more 
physical records, depending upon the size of the object file. 
Each physical record is divided into a number of logical 
records, which are essentially load item blocks defining 
file name, data, or entry point. After the sync byte of the 
first logical record, a file name code of 55H occurs. This 
informs the interpreter that a file name will appear -in the 
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next 6 bytes. The file name is 6 bytes long, padded out 
with blanks. This is the first logical record of the SYSTEM 
tape. 

The next logical record is headed by a data code of 3CH. 
This informs the interpreter that machine language data 
follows in the record. The next byte in the data record is a 
count of the number of data bytes in the record. If this byte 
is a zero, the number of data bytes is 256, otherwise the 
count is the actual number. The next two bytes are the 
load address for the data to follow. They're set in standard 
address format, least significant byte followed by most 
significant byte. Next are the machine-language bytes. 
The last byte of each data record is a checksum byte. A 
checksum is nothing more than a "check byte" formed by 
adding all of the individual data bytes. It is used for 
comparison to another add of the data bytes on load to 
verify that the data has been loaded properly. 

The last logical record on the SYSTEM tape is an entry 
point code of 78H and two bytes that represent the entry 
point for program execution. 
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An Actual Cassette Object File 



The data below represents an actual cassette 
SYSTEM file produced by assembling the program 
below onto cassette. 



C000 12 

C001 13 

C002 OB 

C003 F5 

COOK 7 8 

C005 B1 

C006 2603 

C008 F1 

C009 1 6 F5 

C00E F1 

C00C C9 

C000 

C0000 TOTAL ERBOBS 

/- FILE NAME COCe 



08760 
08770 
08780 
08790 
08800 
08810 
08820 
08830 
088110 

08850 FILLCH 
08860 
08870 
08880 
08890 
08900 
06910 
08920 
08930 

08910 FIL010 
08950 
08960 



ORG 



0C000H 



••••••••••••FILL CHARACTER SUBROUT 1NE« •»»»•••••« «« 

FILLS DESIGNATED AREA WITH GIVEII CHARACTER 
ENTRY: ( A) = CHARACTEI! 

(DE)=AREA 

(BO =HUKBER OF BYTES. 1-655251 IS 65536 
ALL REGISTERS SAVED EXCEPT L'C.DE 



LD 

IliC 

DEC 

PUSH 

LD 

OR 

JR 

POP 

JR 

POP 

RET 

END 



(DE) , A 



BC 
AF 
A , B 



Z.FIL0 1C 

AF 

FILLCH 

AF 



[FILL CHARACTER 
;B.UHP POINTER 
i DECREMENT COUNT 
;SAVE FILL CHAR 
iTEST FOR ZERO 

;G0 IF DONE 

; RESTORE FILL CHAR 

; CONTINUE 
;fi£STORE A 
: RETURN 



SYNC. BYTE , 



■ DATA CODE 

-#DATA BYTES FOLLOWING 
UDAJ> ADT>RESS c C000 



CHECKSUM 



N./T 



-0gf| A5|S5|t6 W ft HC 10 20|3c|0D|00 <-0|l2 13 0B F578 Bl £803 R 18 F5 O? Fl 78 W C0 (6ND1 

MACHINE-LANOUAfiE ENTRY POINT = 
CODE C$00 
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The SYSTEM tape format is identical to that produced by 
T-BUG, the debugger program for cassette-based systems. 
T-BUG has the capability of producing such a file by the P 
(punch) command. Conveniently enough, T-BUG can also 
load in the cassette file by the L command. This means 
that the object tape produced by EDTASM can either be 
read by using the BASIC SYSTEM command or by T-BUG! 

System Considerations for 
EDTASM Object Files 

EDTASM object files represent one huge program. The start 
of the program is defined by the ORG (Origin) pseudo-op at 
the beginning of the program. The size of the program can 
be determined by the location column on the listing. You 
can put buffer areas and working storage for variables 
and tables anywhere in the program that you want. There 
may be a large "open-ended" buffer or buffers in the 
program, generally at the end of the program to build "up" 
into higher and higher memory. You can see an example 
of this structure in MORG, the EDTASM program of Chapter 
13. 

What should the value be for Origin? This depends upon 
the environment in which you are going to use the 
assembly-language program. If your system does not have 
disk, and the assembly-language program does not inter- 
face to a BASIC program, then the program may be ORGed 
at 4980H. T-BUG occupies the area from about 4380H through 
497FH, with an internal stack area building downwards 
from 497FH. When the program is debugged using the 
T-BUG stack, the program may use all of memory for 
storage from the end of the program up to top of memory. 

You might be curious about establishing your own stack 
area. You can do it. In this case, set aside approximately 
100 bytes at some convenient point either in your pro- 
gram, at top of memory, or in some area of memory that 
you know won't be used. The stack should be initialized 
immediately with a 

START LD SP»PEND+100 
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r V 

I V 



or similar instruction (here the stack has been set to the 
end of the program plus 100 bytes). Remember, the loca- 
tion loaded into the stack pointer represents the first 
location to be used by the stack plus one. 



Hints and Kinks 4-2 

Size of Stack 

Many programmers ask "How big should the 
stack area be?" There's no definitive answer. 
Each time a CALL is made, the two bytes of the 
return address are pushed onto the stack. Each 
time a PUSH instruction is executed to 
temporarily store data, two bytes of a 
register pair, IX, or IY are pushed onto the 
stack, A third function that pushes data onto 
the stack is interrupt action. This can occur 
in a disk system with the real-time-clock 
enabled. The "worst case" number of bytes 
used, therefore is: 

2*(number of calls active at any time + 
maximum number of pushes active at any time + 
possible interrupt) 

If 100 bytes are allocated, this allows for 50 
CALL/PUSH/interrupt levels, which are 
probably more than adequate. 



The configuration for assembly-language programs in this 
type of environment is shown in Figure 4-2. 



IfoK 
I.H000H) 



3XK 

(.Q000H ) 



■46K. 
(C000H) 



(I 0H00V,) 




BEGINNING OF T-BUG=4388H 



END OF T-BUG = 497FH 



FREE AREA 

£ FOR YOUR T 

PROGRAM 



Figure 4-2. AL Programs in 

Minimum Configuration 

Systems 
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If the program is to be used together with a BASIC program 
in a non-disk system, then there are two considerations. 
First of all, the ORG can't overlap the BASIC program area. 
The BASIC program builds up in memory from about 4200H 
on. The program statements aren't the only things occupy- 
ing memory, however. Simple variables, arrays, strings, 
and a BASIC interpreter stack are also stored, as shown in 
Figure 4-3. 



LOCATION 









ROM, VIDEO, 
ETC. 




IfeK 


WORKING STORAGE 


^^ STARTS AT ABOUT 


W0QS0H) 


BASIC PROGRAM 
TEXT 

SIMPLE VARIABLES 
ARRAYS 


«^0 THESE BOUNDARIES 

^y CHANGE "DYNAMICALLY" 
*«■ WHILE BASIC PROGRAM 


32 K 
(S000H) 


A 

FREE 
MEMORY 

.1. 


IS RUNNING 


*rBK 
(C000H) 


BASIC STACK 


^t AS BASIC INTERPRETER 
USES STACK 




STRING STORAGE 
AREA 


^- THIS BOUNDARY FIXED BY 
"CLEAR" 




RESERVED FOR 
MACHINE LANGUAGE 


> 

^ THIS BOUNDARY 
ESTABLISHED BY 


00000 tO 




USER IN "MEMORY SHE" 
INPUT 



Figure 4-3. BASIC Memory 
Allocation 

Compute the ORG for the assembly by taking the size of 
the assembled program plus any buffer areas or tables 
outside of the program and subtracting it from your 
system's top of memory plus one (8000H for 16K, C000H for 
32K, or 10000H for 48K). You may use the BASIC stack with 
no problem; if you establish your own stack area, add this 
into the total size to be subtracted. 

Assemble the program with this Origin, and protect this 
memory area by entering the Origin value for 
MEMORY SIZE when BASIC is first entered. The stack area 
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for BASIC will now build downwards from the Origin 
minus one location. 

A special case arises when the assembly-language pro- 
gram uses machine code embedded in the BASIC program. 
In this case, a short assembly-language program becomes 
part of the BASIC program itself and can be loaded easily. 
We'll talk about these techniques in the next chapter. 

Debugging With T-BUG 

After you edit, assemble, and thoroughly desk-check your 
assembly-language program, you should load it along with 
Radio Shack's cassette based debugging program, T-BUG. 
The procedure is simple: 

1. Enter Level II BASIC. 

2. Enter the area of memory to be protected 
(MEMORY SIZE), computed by the procedure 
above. 

3. Type SYSTEM for the ">" prompt. This causes 
the BASIC interpreter to enter the monitor 
mode. 

4. Rewind your object tape and prepare for a 
load. 

5. Enter NAME after the *? prompt. NAME is the 
name you've given your object file for assembly. 
If you haven't named your file, the cassette file 
will be called NONAME. 

6. Your object tape should now load, as indicated 
by the blinking asterisk. 

7. After a successful load, ready the T-BUG cas- 
sette. 

8. Enter TBUG after the *? prompt. 

9. The T-Bug file should now load, followed by 
the *? prompt. 

10. Enter / after the prompt. 

11. T-BUG should now be entered, as evidence by a 
# prompt. 

With both T-BUG and your object program in memory, 
you're ready to do some serious debugging. (This procedure 
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can't be used when a BASIC program is also resident, as the 
BASIC program will "overlay" T-BUG.) First of all, you 
should be familiar with T-BUG commands. These are 
described in the T-BUG manual, and we won't study them 
here, but we'll tell you how to make efficient use of them. 









— H 


in 


ts and Kinks 4-3 






] 


^ec 


ap 


of T-BUG Commands 


#M aaaa 










Display location aaaa 


ENTER (a 


ft 


er 


M) 




Display next location 


X (after 


M 


J 


B, 


PI 


Exit operation 


#R 










Display registers 


tFi 3,3,3.3. 


bbbb 


cccc 


Write cassette from aaaa 


NAME 










through bbbb with starting 
address cccc and file name 
NAME 


#L 










Load a T-BUG or SYSTEM tape 


#B aaaa 










Set breakpoint 


#F 










Restore instruction after 
breakpoint 


#G 










Continue from breakpoint 


#J aaaa 










Jump to location aaaa 



The first rule of debugging is to be sure you've thoroughly 
desk checked the program. This means you've taken a 
listing of the program and gone over it minutely, instruc- 
tion by instruction, to see that it works as planned. This 
may mean some reference to flow charts and design specs 
with larger programs. 

After desk checking as much as possible, the procedure is 
basically, "Get it working (even though it probably will 
run badly) then go back and clean up the flaws." This 
procedure works well as long as the program design is 
substantially correct, and there isn't an overabundance of 
errors. 

To get the program working, use a type of "binary search" 
for flaws. First of all, go ahead and give it a try. Chances 
are that the program will blow up, but it takes an 
extremely strong-willed programmer not to try that first 
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execution in hopes that everything will work right off the 
bat. (It never does!) Reload the program if necessary. 

Having gotten that out of your system, set a breakpoint 
about half way through by using the T-BUG B(reakpoint) 
command. If, for example, the program is about 100 
locations long, set a breakpoint at a location 50 bytes from 
the start of the program. Now use the J(ump) command to 
start the program. One of two things will happen. The 
program may "bomb" again, necessitating a reload, or the 
breakpoint will be reached. 

If the breakpoint is reached, F(ix) the breakpoint and start 
looking at variables and "tracks" of the program up to that 
point. See that variables and actions appear to be correct. 
If you find strange results, write them down and start 
correcting them one by one by setting new breakpoints at 
an earlier condition. Don't be too picky about testing every 
possible condition. 



• Hints and Kinks 4-4 ■ 



How Does T-BUG Breakpoint? 

When you put a breakpoint at a specific 
location, T-BUG puts a CD 80 43 at that 
location and the next two bytes. This is a 
' 'CALL 4380H' ' that calls the T-BUG breakpoint 
routine. F(ixing) the breakpoint restores the 
original three bytes. 

Be careful in breakpointing that the three 
bytes temporarily destroyed in breakpointing 
are not used as variables or instructions by 
the code to be checked. 



If results seem to be correct on cursory looks up to this 
point, set a breakpoint about half-way into the remaining 
area, and repeat the procedure. Zero-in on the errors in 
the same fashion. 

Patching 

You have two alternatives in correcting errors as they're 
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found in the program. You can reassemble and reload, or 
you can patch. If you have never used a patching tech- 
nique; stay tuned and we'll explain with an example. 

Figure 4-4 shows an EDTASM program from MQRG in 
Chapter 13 with two errors. The subroutine is missing an 
OR C, and the JR Z»FIL010 is erroneously 
JR NZtFILOlO. (Obviously I had a thorough desk check 
here!) 



8583 




08770 
08780 
08790 
08800 
08810 
08820 
08830 
088110 


6583 


12 


08850 


85811 


13 


08860 


8585 


0B 


08870 


6586 


F5 


08880 


0587 


76 


08890 
08900 


6588 


2003 


08910 


858A 


F1 


08920 


858B 


1BF6 


08930 


858D 


F1 


089«0 


858E 


C9 


08950 
08960 


0000 




08970 


00000 TOTAL 


ERRORS 



0HG 85831! 

ii<iniiii«»»FiLL CHARACTER SUBR0UT INE«««*«*»««»«»» 

• FILLS DESIGNATED AREA UITH GIVEN CHARACTER 

• ENTRY! ( AlrCHARACTER 

• (DE)=AREA 

' (BC)=HUHBER OF BYTES, 1-65525! IS 65536 

« ALL REGISTERS SAVED EXCEPT BC.DE 



LD 


( DE) , A 


IFILL CHARACTER 


II.'C 


DE 


:BUIiP POINTER 


DEC 


BC 


; DECREMENT COUNT 


PUSH 


AF 


;SAVE FILL CHAR 


LD 


A,B 


;TEST FOR ZERO 


OR 


C 


; •••HISSING*'* 


J 11 


IIZ , FILO 10 


;GO IF DOHE«*«S/B 


POP 


AF 


tRESTORE FILL CHAR 


JR 


FILLCh 


ICOIITINUE 


POP 


AF 


; RESTORE A 


RET 




; RETURN 



Figure 4-4. Flawed Program 

In testing the program, we loaded the A register with 23H, 
the DE register pair with 8000H, and the BC register pair 
with 64H to fill locations 8000H-8063H with 23H. We break- 
pointed on the RET by B858E. When the breakpoint was 
reached, it turned out that only the first byte at location 
8000H had been filled. 

In checking through the code, we found that the 
JR NZ»FIL010 should have been a Z. Rather than 
reassembling, we decided to patch the code. The 
JR NZtFILOlO assembles as 2003H. By looking in 
Appendix II (or the Assembler manual), we found that a 
JR Z would be 28XXH. This is simple to fix using T-BUG — 
we simply perform a M 8 588 2 2 8 to change the 
location to a J R N Z » F I L 1 and record the patch in a 
list of patches. 

Having patched, we tried again. This time, with an iden- 
tical procedure, we found 23H stored from 8000H through 
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8583H! It seems 23H was stored until the program was 
destroyed! After further head scratching, we found that we 
had left out an OR C instruction! 

This time we found we couldn't easily patch because we 
couldn't fit in another one-byte instruction between the 
last bit of location 8587H and the first bit of location 8588H! 
How do we patch in this case? 

In cases like this, we can jump out to a patch area, "gin 
up" some code to make the change, and jump back into the 
routine. A patch area is any unused area that can be used 
to store temporary fixes. In this case, since we weren't 
using locations C000H and up, we designated that as a 
patch area. 

To get to the patch area, we had to put the three bytes of a 
J P somewhere in the code. We put them into the locations 
that would have normally held DEC 5C as shown in 
Figure 4-5. We deleted the three instructions of DEC BC , 
PUSH AF, and LD A »B and substituted a JP C000H 
instead. 



Location 




8583 


11 


&58H 


13 


8585 


0B 


8586 


F5 


8587 


78 


8588 


26]03 


858A 


■Fl 


858B 


I6F6 


&58D 


Fl 


858E 


C9 




PREVIOUSLY 




PATCHED 
JR2, FIL910 



Old 



DEC EC 
PUSHAF 

LD A,B 



Patched 



12 

13 

C3 

00 

C0 

1803 

Fl 

18F6 

Fl 

C9 



JP C000H 



Figure 4-5. Patching to 
Flawed Program 
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How did we know what code to put in for the JP? By con- 
sulting the Appendix, by referring to the Assembler 
manual, or by looking through the listing until a 

similar type instruction was found! 

At the C000H patch area, we put in machine code repre- 
senting the three deleted instructions, machine code for 
OR C, and a J P back to location 8588H, as shown in Figure 
4-6. You can patch virtually any program this way. 



Hints and Kinks 4-5 

Hand Assembling 

There are still some programmers that I 
know of that persist in ' 'hand 
assembling. ' ' These are the same types of 
people that collect balls of string eight 
feet in diameter, cultivate their own 
wheat in their city plot, and try to 
interface Baudot teletypes to their 
TRS-80si 

What we are doing in patching is a small 
exercise in ' 'hand assembling. ' ' Instead 
of letting the assembler look up opcodes 
and resolve addresses, we are doing it 
ourselves. Hand assembling is not too much 
of a chore in this case, since we're 
working with only a few instructions. We 
can simplify it by looking at our listings 
for identical or similar instructions and 
use their formats to make the patches. 
However, when there are many instructions 
to be assembled, it's probably best to let 
the assembler do the job — even to the 
extent of running a short assembly to get 
the patches! I've spent too many nights at 
some customer's site hand assembling 
patches into a computerized system to 
advise you differently. Help stamp out 
hand assembling! 
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LOCATION CONTENTS CODE NOTES 

C000 0b DEC BC ) 

I F5 PUSH AF 



RESTORE ORIGINAL 
INSTRUCTIONS 



NEW INSTRUCTION 



2 78 LD A,B 

3 Bl OR C 

4 C3 JP 8588H I 

p- nn > JUMP BACK 

6 85 J 

Figure 4-6. Patch Area Contents 

With the patch in place, we tried the subroutine again, 
and it worked fine for the one case. 

This patching process requires some effort, and you may 
not want to use it. However, you can become very pro- 
ficient at it and use it to advantage to debug large pro- 
grams that take a great deal of time to reassemble because 
of printing time. Hard thinking vs. time: it's a tradeoff 
you'll have to assess. 

A patched program can be written out to cassette at any 
time. The advantage is that the patches don't have to be 
reentered when the program blows up the next time. 
Also, as long as you're writing out to cassette, why not 
include the T-BUG area along with the program area? That 
way the entire program area, T-BUG and all, can be read in 
by a SYSTEM command to simplify reloading. The entry 
point for T-BUG is 17312 decimal. 

Disk Assembler Files 

The final output of a set of edits and assemblies and a load 
operation with the Disk Editor/Assembler package is a 
command file (/CMD) on disk. You can load and execute 
this command file by simply typing the name of the file 
after the DOS READY prompt. In most cases, however, you 
must do some debugging before the program is ready to 
run in this fashion. 

The memory area specified to the Loader is, like EDTASM 
programs, dependent upon the environment in which you 
are going to run the program. Since the program will 
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normally be loaded by TRSDOS, it must not overlap the 
TRSDOS area, which usually ends at 6FFFH. This will 
enable DUMP commands to be used to save patched ver- 
sions of the program. 

If the program is to run "stand-alone," without interface to 
Disk BASIC, then the area from 7000H through top of 
memory is available for program use. This won't conflict 
with use of the Disk DEBUG package, as it loads into an 
overlay area below 7000H. If DEBUG were used for 
debugging, its stack area would be internal to the DEBUG 
program and wouldn't conflict with program use of the 
7000H and up area. Of course, a separate stack area could 
be maintained by the program if you want. This configur- 
ation is shown in Figure 4-7. 

LOCATION 

ROM, VIDEO, 

ETC. 



IfcK 

(H000H} 

7000H 

3ZK 
(8000H) 

H8K 



{\0000H~) 



TRSDOS, 
OVERLAYS 



i=R£E AREA 
FOR YOUR 

PROGRAM 



~ END OF TRSDOS 

*A — AND OVERLAY 



AREA AT 6FFFH 



Figure 4-7. AL Programs in 

Disk Systems Without 

BASIC Interface 



If you're going to use the program together with Disk 
BASIC, then the area from 7000H on is used for storage of 
the BASIC program, simple variables, arrays, strings, and 
the stack as shown in Figure 4-8. This allocation scheme is 
identical to Level II BASIC, except that the memory allo- 
cation area starts higher in memory. 
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LOCATION 





W000H] 



1000 a 

(Q000H*) 



<t8K 
(C000W) 






ROM, VIDEO, 
ETC. 



TRSDOS, 
OVERLAYS 



BASIC PROGRAM 



TEXT 

' SJMPLEVARIABLESj 
ARRAYS 

FREE 
MEMORY 



i 

BASIC STACK 



STRING STORAGE 
AREA 



RESERVED FOR 
MACHINE LANGUAGE 



BASIC PROGRAM 
STARTS AT ABOUT 
7808H 



THESE BOUNDARIES 
CHANGE "DYNAMICALLY" 
WHILE PROGRAM RUNNING 



THIS BOUNDARY CHANGES 
AS BASIC INTERPRETER 
USES STACK 

THIS BOUNDARY FIXED 
BY "CLEAR" 

■ THIS BOUNDARY ESTAB- 
LISHED BY USER IN 
"MEMORY SIZE" INPUT 



Figure 4-8. AL Programs in 
Disk Systems With BASIC 

Interface 



The plan here is for you to specify the load address high 
enough in memory for both BASIC and the assembly-lan- 
guage program to coexist peacefully. Compute the loading 
address by making a test load and observing the size of the 
final configuration. Add to this size any external buffer or 
table areas and approximately 100 bytes for an external 
stack, if one is to be used. Subtract this total from the top 
of memory value plus one. The result is the load address 
you'll specify to create the command module for the pro- 
gram. This process is shown in Figure 4-9. In many cases, 
of course, you'll have more than enough memory to be 
fairly "sloppy" in specifying the load address. 
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___[ 



LOAD 
ADDRESS 



TOP OF 
MEMORY 
/64K,\ 

( 48K - I 
\ 32K / 



ETC. 



BASIC 
STACK 



STRING 
STORAGE 



PROGRAM 
AREA 



BUFFER OR 
TABLE AREAS 



EXTERNAL STACK 
USED BY PROGRAM 



"MEMORY SIZE" 
LIMIT 



AS DETERMINED 
BY TEST LOAD 



AS REQUIRED BY 
PROGRAM 



ALLOW 100 BYTES 



Figure 4-9. Computing the 
Load Address 



Debugging with DEBUG 

Once you've created a command module, you're ready to 
begin debugging. Actually, you should have already done 
the bulk of the debug! Prior to using DEBUG, you should 
have done a thorough and detailed check of your 
assembly-language code. This desk check will usually 
reveal errors in logic and implementation that will be much 
easier to correct by reassembly than by patching during 
debugging. 
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Hints and Kinks 4-6 

Desk Checking 

A typical desk check would involve reviewing 
the specs and flow charts, together with the 
program listing(s) to see that no logical 
errors have been made. 

Next, you might start with the simplest 
subroutines and ' 'walk through' ' them, 
instruction by instruction, using sample data. 
Write the contents of each register down on 
paper as you follow the instructions. Work 
your way up through the program levels until 
you've gone over all the code once. Reassemble 
if necessary. 

Next, go through the same process again. Look 
for errors! They're there. (It might help to 
pretend that it's someone else's code.) This 
process should be repeated until you've gone 
through all code once without finding new 
errors. Yes, this is a lot of work. But it's 
much easier to correct errors now than during 
program execution. 

When you're satisfied, start the actual 
''on-line'' debugging. You'll probably say 
' 'What a stupid error - I should have seen 
that! ' ' (It always happens to me . , . . ) 



To use DEBUG, first load DEBUG by typing in DEBUG after 
the TRSDOS DOS READY prompt. Then type in the name of 
the load module you created during the loading process to 
load it into memory in the area you specified. Now hit 
BREAK, and you will be in DEBUG. 

The Disk DEBUG is quite a bit more powerful than T-BUG. 
Probably one of its most useful features is the ability to set 
multiple breakpoints. T-BUG allowed only one 
breakpoint, making it fairly easy for the program to take a 
path to oblivion. In addition to breakpointing, DEBUG 
allows for modifying memory or registers, displaying areas 
of memory in ASCII or hexadecimal, and single-stepping 
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the program one instruction at a time. These functions are 
described in the TRSDOS and Disk BASIC manual, and we'll 
be giving you some more examples of their use here. 



1 

Re 


-lints and Kinks 4-7 

oap of DEBUG Commands 


A 


Show display in ASCII 


C 


Single step instruction, 




CALLs in full 


Daaaa<space> 


Display from location aaaa 


Gaaaa( ,bbbb 


Execute at location aaaa with 


( , cccc ) ) 


optional breakpoints 




bbbb, cccc, . . . 


H 


Display in hexdecimal 


I 


Single step instruction 


M(aaaa)<space> 


Set modification address to aaaa 




and display data 


Rrp dddd 


Load register pair rp with dddd 


<space> 




S 


Set display to full screen 


U 


Set dynamic display update mode 


X 


Cancel command, set display to 




register mode 


', 


Increment memory display to next 




block 


- 


Decrement memory display to last 




block 



The debugging process with DEBUG is very similar to the 
one described under T-BUG use. The approach is again to 
focus in on failing areas of the program by a type of 

"binary search." 

Start execution of your program by entering a G(o) 
command to DEBUG, with one or more breakpoints 
specified. If the program gets to the breakpoint, go back 
and look for "tracks" of proper program operation — flags 
set properly, variables and buffers with correct values, and 
the like. If errors are found, concentrate on the failing 
area by setting a breakpoint prior to the error and 
observing results. If the program doesn't get to the 
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breakpoint, hit BREAK to get back to DEBUG and then try 
another execution with an earlier breakpoint. 

The DUMP command can be used to advantage in 
patching programs. (If you skipped over the discussion of 
patching under T-BUG, you may want to read it to get 
familiar with the technique.) When your program has 
been patched, you can save it on disk by doing something 
similar to: 

DUMP NAME ( S T A R T = X ' 8 ' t E N D = X ' 9 A 4 5 ' ) ♦ 
This creates a new file on disk with name, NAME, and 
extension, /CIM (Core Image Module). You can now load 
this patched file eliminating a tedious patching operation 
each time the program "blows up." 



■ Hints and Kinks 4-8 



How Do You Know Where A 
Relocatable Program Is? 

One of the problems in link loading is knowing 
where a location is. Subroutines can be found 
by looking at the load map listing of all 
globals (loader M command) . Record this 
information after the load. 

It's also easy to put in global symbols, not 
only for subroutines but also for other 
selected points in the program. These will 
then be displayed on the load map, and you'll 
avoid some hexadecimal arithmetic. 

A second trick is to use the -P command to 
load each module at convenient locations such 
as 8000H, 8200H, 8400H, etc. This makes the 
hexadecimal arithmetic a little easier. 



To use DUMP, G(o) to location 402DH. This reboots TRSDOS 
but does not affect any of the user memory area. Now 
enter the DUMP command with the proper memory limits 
specified. By the way, if you've patched outside your 
program area, be sure to include that area by altering the 
START or END address accordingly. 
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The DUMP command is best used with a "clean" program. 
When you have found an error and established the proper 
patch, reload the program; do not execute and make the 
patches and then DUMP the patched, unexecuted program. 
This will eliminate strange results caused by patching an 
altered program. 

However, if you want, you can also use the DUMP to save 
the state of any program at any given time during 
execution. This enables you to load in the program and 
easily reconstruct the conditions that caused the blowup. 

Interfacing Assembly-Language and 
BASIC Programs 

Level II and Disk BASIC both have the capability of calling 
assembly-language programs while in the middle of BASIC 
program execution. This means that time-critical parts of 
the BASIC program can be coded in assembly language to 
speed up program execution, or that BASIC can be used for 
operations which are harder to code in assembly language, 
such as string input, report display, and "number-crunch- 
ing." 

Level II USR Calls 

The Level II procedure for calling an assembly-language 
program is as follows: 

1. POKE the address of the assembly-language 
routine to be called into locations 16526 and 
16527. The two bytes represent the least signi- 
ficant and most significant bytes of the address 
in standard Z-80 address format. 

2. Any time a call to the assembly-language 
routine is required, call the routine by a state- 
ment such as A = USR(M). 

The USR function uses two arguments, A and M. These can 
be "dummies." For example, a call to the assembly- 
language routine can be made by A = USR(0) with 
variable A being ignored. The USR function simply causes 
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the BASIC interpreter to pick up the address from locations 
16526 and 16527 and execute a CALL to that address. The 
assembly-language routine must have a RET at the end to 
cause a return back to the interpreter at a point after the 
CALL. Figure 4-10 shows a typical Level II USR sequence 
for a short assembly-language routine located at location 
C000H. 

100 REM CALL l.'RITE BOOK ROUTINE AT C000K 

200 REM FIfiST POKE LEAST SIGNIFICANT BYTE OF ADDRESS 

300 POKE 16526,0 

100 REM NEXT POKE HOST SIGNIFICANT BYTE OF ADDRESS 

500 POKE 16527,192 

600 REM HOW CALL ROUTINE BY USR FUNCTION 

700 A=USR(H) 

600 REM RETURN AFTER USR ROUTINE HERE 

Figure 4-10. Level II 
USR Sequence 

You can make calls to more than one assembly- language 
routine easily by setting up 16526,7 with the proper 
address just prior to the USR call. You can use as many 
assembly-language routines as you need by preceding each 
call by a POKE of the address into 16526,7. Of course, if 
you use only one assembly-language routine, you only 
have to set up 16526,7 once at the beginning of the BASIC 
program. 

The M argument allows the BASIC program to pass one 
16-bit argument to the assembly-language routine. The 
calling sequence is the same except that M must be a 
variable (or expression) that is equated to -32768 to 32767. 
When the assembly-language routine is entered, it must 
pick up the argument by performing a CALL to ROM at 
0A7FH. This CALL passes the 16-bit argument back in the 
HL register pair. 

If you wanted to pass the argument back the other way — 
in this case, pass a 16-bit value in HL back to the BASIC 
program — you would make a JP 0A9AH at the end of the 
assembly-language program rather than a RET. Figure 
4-11 illustrates the passing of a single argument back and 
forth; here, a variable passed to a shift routine. The shift 
routine shifts the value three bits left and passes back the 
result. The BASIC program then displays the result on the 
screen. 
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00100 ORG OCOOOH „,„ 

00110 ;SHIFT ROUTINE. SHIFTS CONTENTS OF HL LEFT 3 BITS AND 
00120 ; PASSES BACK THE RESULT 

PICK UP ARGUMENT 
SHIFT ONE BIT POSITION 
SHIFT TWO BIT POSITIONS 
SHIFT THREE BIT POSITIONS 
RETURN ARGUMENT 



cooo 


CD7F0A 


00130 


SHIFT 


CALL 


0A7FH 


C003 


29 


0011 




ADD 


HL.HL 


coot 


29 


00150 




ADD 


HL.HL 


C005 


29 


00160 




ADD 


HL.HL 


C006 


C39AOA 


00170 




JP 


0A9AH 


0000 




00180 




END 





00000 TOTAL ERRORS 



100 REM TEST PROGRAM FOR SHIFT ASSEMBLY LANGUAGE PROGRAM 

200 POKE 16526 ,0 

300 POKE 16527,192 

100 INPUT "VALUE=";M 

500 A=USR(M) 

600 PRINT "0RIGINAL=";M, "SHIFTED RESULT=";A 

700 GOTO «00 



Figure 4-11. Assembly-Language/BASIC 
Argument Passing 



Disk BASIC USR Calls 

The procedure for interfacing assembly-language pro- 
grams to Disk BASIC is much the same as that for Level II 
BASIC. The chief difference is that more than one USR call 
is permitted. The format of the Disk BASIC USR call is 
X=USRn(M) where n is through 9, permitting ten 
separate USR calls. Each USR call is first defined by a 
DEFUSR function of the form DEFUSR = &HXXXX where 
XXXX is the address of the assembly-language subroutine 
in hexadecimal format. 

The CALL to 0A7FH to pass an argument from BASIC to the 
assembly-language routine and the JP to 0A9AH to pass an 
argument back to BASIC is the same as in Level II BASIC. 
The sequence for the same assembly-language program as 
above is shown for Disk BASIC in Figure 4-12. 



100 REM TEST PROGRAM FOR SHIFT ASSEMBLY-LANGUAGE PROGRAM 

200 DEFUSR0=4HC000 

300 INPUT "VALUE=";H 

H00 A=USR0(M) 

500 PRINT "0RIGINAL=";K. "SHIFTED RESULT=";A 

600 GOTO 300 



Figure 4-12. Disk BASIC USR 
Sequence 

96 



Handling Multiple Arguments 

Many times it is necessary to pass more than one argu- 
ment between Level II or Disk BASIC and an assembly- 
language routine. Since the USR call permits you to pass 
only one 16-bit value, how can you pass multiple argu- 
ments? There are a number of different ways to 
accomplish this. 

Packing Arguments 

First of all, arguments may be packed into 16 bits. If, for 
example, an x and y screen position must be specified, then 
two 8-bit fields, one in H and one in L may be used. If you 
need four arguments and they can be held in four-bit 
values, then you can use 4 four-bit fields in HL. 

Figure 4-13 shows the technique of storing data in a 
common memory area in an example that SETs a series of 
points in the assembly-language routine. The points are 
defined in a table starting at location 32 700 and 
terminated with a - 1 . 



CD7F0A 

E5 

DDE1 

DD6601 

DD6E00 

7C 

FEFF 

C8 

3E1F 

77 

DD23 

DD23 

18ED 

TOTAL 



00100 
00110 
00120 
00130 
0011)0 
00150 
00160 
00170 
00180 

00190 

00200 
0021 
00220 
00230 
0021)0 
00250 
260 
00270 
00280 
00290 
00300 
00310 
ERRORS 



ORG 0C000H 
lllllilllllllfflllllllflllllfllllillllflllilllillligilll 

I ROUTINE TO PUT AN "0" IN DISPLAY. 

ENTRY: BASIC HL LINKAGE POINTS TO TABLE OF ADDRESSES 

EACH TABLE ENTRY IS SCREEN CHARACTER POSITION 

TO BE SET. TABLE TERMINATED BY -1. 

SCI'IffftlfKlllllllllfltltlCIIIHIIIIlfllllftlfllilMIll 



CALL 

PUSH 

POP 

LD 

LD 

LD 

CP 

RET 

LD 

LD 

INC 

INC 

JR 

END 



0A7FH 

HL 

IX 

H.(IX+1 ) 

L.( IX+0) 

A,H 

OFFH 

Z 

A, '0' 

(HL) ,A 

IX 

IX 

SET010 



C0O0 
C003 
COOK 
C006 
C009 
COOC 
COOD 
COOF 
C010 
C012 
C013 
C015 
C017 
0000 
00000 

100 'BASIC DRIVER TO STORE OS IN DISPLAY 

150 CLS 

200 POKE 32700,32: 'POKE 3E20H 

300 POKE 32701 ,62 

1100 POKE 32702,31 : 'POKE 3E22H 

500 POKE 32703.62 

600 POKE 32701) ,36: 'POKE 3E2DH 

700 POKE 32705.62 

800 POKE 32706 ,255 : 'POKE -1 

900 POKE 32707,255 

1000 DEFUSR0=4HC000 

1100 B=32700: 'START OF POKED DATA 

1200 A=USR0(B) : 'HAKE CALL TO AL ROUTINE 

1300 GOTO 1300:'L00P HERE TO RETAIN DISPLAY 



:GET ADDRESS OF TABLE 
;KOW IN STACK 
;N0W IN IX 

;HS BYTE 

;LS BYTE 

;GET MS BYTE 

;TEST FOR END 

;G0 IF DONE 

:0 FOR STORE 

:STORE 

iBUMP PHTR 

; TWICE 

; CONTINUE 



ie 


32 


■ 


1 


62 


2 


34 


3 


62 


4 


36 


5 


62 


6 


255 


7 


255 



Figure 4-13. Passing Multiple 
Arguments 
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Passing The Arguments 

A second method is to pass the arguments between BASIC 
and assembly language by using a common memory area. 
Arguments can be POKEd into the memory area in BASIC 
or obtained from the area by PEEKs. The assembly- 
language code, of course, can easily load or store the 
values. You can define this common memory area as part 
of the assembly-language program area itself or in a 
convenient location outside of the assembly-language 
program. 

Another way to pass the arguments is to use the contents 
of HL to define the address of a parameter list. Argu- 
ments can then be picked up or stored in the list by the 
assembly-language program. Of course, the address of the 
parameter list can be passed back from the assembly- 
language routine to BASIC. The parameter list may be 
established in BASIC by using a dummy string or array. 
You can then determine the address of the array or string 
by a VARPTR function in BASIC and pass it to the 
assembly-language routine. 

In the next chapter we'll look at a special case of inter- 
facing assembly-language routines: embedded machine- 
language code in BASIC programs. 



98 



Chapter 5 

Embedded Machine Code in BASIC 

In this chapter, we'll discuss special techniques for 
embedding assembly-language code in BASIC programs. 
By this technique, short assembly-language routines can 
be included as DATA statements or strings in the BASIC 
program. One advantage to this is the ability to store, 
load, and execute the BASIC and assembly-language code 
as one file. Additionally, you don't have to compute the 
addresses of the assembly-language routines manually 
and include them in the BASIC code — they are 
automatically found by the BASIC program itself. 

The drawbacks to this method are: (1) it works best with 
short code segments that are relocatable; (2) it requires 
some conversion of the hexadecimal machine code values 
into decimal values to include in the BASIC code. 

Relocatable Code 

Before we show several methods for embedding machine 
code, let's first talk about relocatability. As it applies to 
embedding, "relocatability" does not have the same 
meaning here as when we used the term with the Disk 
Assembler and Loader. The Loader relocates code by 
adding a relocation bias to addresses in instructions in 
order to obtain the correct address for the instruction no 
matter where in memory the instructions are moved. How- 
ever, here we're talking about instructions whose machine 
code form is constant no matter where in memory the 
instruction is. These instructions would not have the 
relocation bias added to them during the loading process. 
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As a rule of thumb, any instruction that does not contain a 
memory address is relocatable. For example, 



LD 
AND 
LDIR 
LD 



A»B 
07FH 

A»(HL) 



are all instruction types which have the same machine 
code form no matter where in memory they're located. 

Instructions that contain addresses, however, may or may 
not be relocatable. If the address reference is to somewhere 
inside the program and if the program is moved around in 
memory, the address in the instruction should be con- 
stantly changing depending upon the area of memory in 
which the program is loaded, as shown in Figure 5-1. 



8000H 



8213H 



C000H 



C213H 



C3 13 82 



JP NEXT 



NEXT EQU $ 



C3 13 C2 



JPNEXT 



NEXT EQU $ 



FIRST LOCATION 
OF PROGRAM 

NEXT=8213HAND 
"JP NEXT" IS C31382. 



SECOND LOCATION 
OF PROGRAM 



NEXT = C213H AND 
"JP NEXT" IS C313C2. 



Figure 5-1. Non-Relocatable Direct Address 
Instruction 



If the address in the instruction refers to a memory 
location that is not inside the program, such as a ROM 
subroutine or a fixed buffer in high memory, then even 
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though the program may move, the instruction containing 
the address is relocatable, as shown in Figure 5-2. 



8000H 



C000H 



E000H 



3A00E0 LDA,(E000H) 



3A 00 E0 



LDA,(E000H) 



FIRST LOCATION 
OF PROGRAM 



CODE FOR "LD A, (E889H)" 
IS 3A 00 E9 



SECOND LOCATION 
OF PROGRAM 



CODE FOR "LD A.(E039H)" 
IS 3A 99 E9 



Figure 5-2. Relocatable Direct 
Address Instruction 

Some examples of instructions that are not relocatable are 
LD HL > TABLE (where TABLE is inside program) 
LD A» (FLAGS) (where FLAGS is in program) 



JP 



• NEXT 



(where NEXT is inside program) 



Jump instructions that jump to locations inside a program 
are always non-relocatable, unless they are "Jump Rela- 
tive" instructions or DJN2 instructions. The reason for 
this (check out the instruction formats in Appendix II) is 
that the standard JP type instructions always have an 
address in bytes 2 and 3 of the instruction. This address, of 
course, should change as the program is moved around in 
memory. 
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Hints and Kinks 5-1 



JR and DJNZ Instructions 
The format for the JR and DJNZ instructions is 

BYTE BYTE I 

lorcopgi z-2.mT ^~ displacement 
the opcode is fixed: 
JR=18H» JR C=1CH» JR NC=30H» 
JR Z=28H» JR NZ=20H» DJNZ=10H 

The second byte is computed by counting 
forward or back from the instruction following 
the JR or DJNZ. Since the JR or DJNZ is two 
bytes long, a jump to the following 
instruction would have a displacement in the 
second byte of 0; a jump to the JR or DJNZ 
itself would have a displacement of FEH or -2! 
If you're weak on hex math, count back one 
byte at a time from the relative instruction 
like this: FDH, FC, FB, FA, F9 , etc. to get 
the second byte. Best not to try this with an 
instruction 102 bytes back! 



The JR and DJNZ instructions, however, use a 
displacement field of one byte in the instruction. This 
displacement field is used to compute the jump address by 
addition to the current contents of the program 
counter. Therefore, the jump address (or effective 
address) is always relative to the current location of the 
instruction. If the jump is to an instruction 6 bytes 
forward, the format of a JR NEXT is always 18 04; if the 
jump is to an instruction 6 bytes back, the format of a 
JR NEXT is always 18 F8. (Remember, the program 
counter points to the next instruction after the JR by the 
time it is added to the displacement, making the dis- 
placement field a value two bytes less than the displace- 
ment from the start of the JR!) 

Because the JR and DJNZ are fixed values wherever the 
program is relocated in memory, they're relocatable 
instructions you can use in place of J P s . Of course, the 
jump address must be within 129 bytes forward or 126 
bytes back of the JR or DJNZ. 
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If you're using the Disk Assembler, it automatically flags 
in the machine code section of the listing which instruc- 
tions are relocatable and which instructions are non-relo- 
catable. A byte that is relocatable is followed by a blank, 
while a single quote is used after an address. If the 
machine code for an instruction doesn't have a quote, the 
instruction is relocatable. 



Hints and Kinks 5-2 

Non-Relocatable Instructions 


The following ins 


tructions are not relocatable 


unless they reference memory locations that 


are fixed and out 


side the program area in 


question : 




Load A 




from memory 


LD A » (nn) 


Store A 


LD (nn ) >A 


Load register 




pair 




immediate 


LD dd .nn 




dd = BC »DE »HL ,SP , IX , IY 


Load register 




pair memory 


LD dd »(nn) 




dd = BC »DE »HL »SP , IX , IY 


Store register 




pair 


LD (nn ) .dd 




dd = BC »DE >HL tSP > I X »IY 


Uncondi- 




tional jump 


JP nn 


Conditional 




jump 


J P cctn n 




cc = NZ .Z »NC >C »P0 »PE ,P »H 


Uncondi- 




tional CALL 


CALL nn 


Conditional 




CALL 


CALL ccmn 




cc = NZ »Z »NC ,C »P0 .PE ,P .M 
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Embedded Machine Code 
By DATA to Memory 

The first method of embedding machine code is to include 
the code in DATA statements and then move it to a fixed 
location in memory. Let's see how this works on a simple 
program. Figure 5-3 shows the listing for a short program 
to scroll up the screen one line. 



8000 




00100 




ORG 


8000H 










00110 


;SCROLL 


PROGRAM 


. SCROLLS 


UP 


SCREEN ONE LINE. FILLS 






00120 


:LAST LINE WITH 


BLANKS 






8000 


21103C 


00130 


SCROLL 


LD 


HL,3COOH+61 


;START 


8003 


1 1003C 


001H0 




LD 


DE, 3C00H 




DESTINATION 


8006 


01C003 


00150 




LD 


BC, 1021-611 


;1> BYTES 


8009 


EDB0 


00160 




LDIR 






;SCR0LL 


800B 


21C03F 


00170 




LD 


HL.3FC0H 




;ADDRESS OF LAST LINE 


800E 


3E20 


00180 




LD 


A. ' ' 




; BLANK CHARACTER 


8010 


0640 


00190 




LD 


B.6D 




;} BYTES PER LINE 


8012 


77 


00200 


LOOP 


LD 


(HL) ,A 




;ST0RE BLANK 


8013 


23 


00210 




INC 


HL 




:B0HP POINTER 


8011 


10FC 


00220 




DJNZ 


LOOP 




;G0 IF HOT 51 


8016 


C9 


00230 




RET 






: RETURN 


0000 




002H0 




END 








00000 TOTAL 


ERRORS 













Figure 5-3. SCROLL Program 
Example 

The program contains all relocatable code and is meant to 
be called from BASIC by the techniques discussed in 
Chapter 4. To embed the code in a BASIC program by that 
method, take the following steps: 

1. Assemble and debug the program completely. 

2. Convert the hexadecimal values for the 
machine code into their decimal equivalents. 

3. Put these decimal equivalents into a DATA 
statement in the BASIC program. 

4. Move the DATA values to a predetermined area 
of memory at the beginning of the BASIC program. 

5. Set up the USR address and call the machine 
code as required. 

These steps have been carried out in Figure 5-4. The 
resulting BASIC program is a simple test of the program; 
two versions are shown, one for Level II and one for Disk 
BASIC. (Set MEMORY S I ZE to 32767.) 
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■Hints and Kinks 5-3- 



BASIC Address Computation 

In using machine code in higher memory with 
B ASIC- 
Certain BASIC functions that operate only with 
16-bit integer values don't permit "absolute" 
values from 32768 through 65535. An 
"overflow" error results. When addressing 
memory locations with these functions, the 
interpreter must be fooled into thinking the 
memory location value is a legitimate integer 
value from -32768 to +32767. 

This problem only occurs for memory locations 
in the upper 32K of memory, 32768 through 
65535. When you reference these locations, 
they must be in the form of the expression — 

L0CATI0N-G553G 

This problem occurs for the FOR ... TO 
command, DEFUSR command, PEEK command, POKE 
command, and others. 



Example : 



100 PRINT PEEK(BOOOO) does not work, 

but 

100 PRINT PEEK(G0000-G553B) does. 



100 BEi: EMBEDDED MACHINE CODE BY DATA TO MEMORY 

200 FOB 1=32768 TC 32790 

300 READ A 

«00- POKE (1-65536) . A 

500 NEXT I 

600 DEFi)SB0 = &H8000: ' POKE 16526, 0:'FQH LEVEL II 

700 ' p"0KE~16527~,1iB; 'FOB LEVEL II 

800 JCi.USROiO.l_: ' X=USR(0 ) : 'FOR LEVEL II 

900 GOTO 800~ 

1000 REM THESE DATA VALUES ARE THE 23 BYTES OF SCROLL IK DECIKAL 

1100 DATA 33. 6«, 60, 17. 0,60, 1,192, 3. 237, 176, 33, 192, 63, 62, 32. 6, 6 '1 

1200 DATA 119.35.16,252,201 

__ DISK BASIC 
LEVEL II BASIC 



Figure 5-4. DATA-to-Memory 
Embedded Machine Code 
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In this case, relocatable code was used in the SCROLL 
program. However, since the predetermined area of 8000H 
was used, the code could have included non-relocatable 
instructions, as long as the assembly was performed with 
an ORG of 8000H. 

This method can be used for any size of assembly-language 
program. It does get quite tedious, however, to convert the 
hexadecimal values into decimal for large amounts of code. 
A few other disadvantages include the necessity of fixing 
the memory area for the assembly-language code and the 
possibility of having to "merge" the DATA table with other 
DATA values in the BASIC program. 



Embedded Machine Code 
By CHR$ Strings 

This method of embedding machine-language code into a 
BASIC program uses the CHR$ function of Level II or Disk 
BASIC to construct a string of machine-language values. 
You can then find the location of the string by the VARPTR 
function and make a call by the USR function. 

You must carry out the same preliminary steps as in the 
first method: the program must be assembled, debugged, 
and converted to decimal values. The decimal values must 
then be used in a BASIC character string such as ZZ$=CHR$ 
(xx) + CHR$(xx)+CHR$(xx)+ , , . where "xx" represents the 
machine code decimal values. 

A BASIC program that calls SCROLL and uses this method 
is shown in Figure 5-5. The VARPTR function is used to 
find the location of string ZZ$. Remember from the Level II 
manual that VARPTR points to a parameter block for the 
string. The parameter block has the form shown in Figure 
5-6. The second and third bytes represent the actual 
location of the string. 
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50 
100 
+ C11 
+ C1I 
+ CII 
200 
300 


?EK CHR$ EMBEDDED MACHINE 

At=CHR$(33)+CHR$(61 >+CHR$ 

U(1I + CHB$(192) + CI1H5(3)+CI 

U(192)+CHR*(63)+CHB$(62)+ 

U(35> + CI1B$(16)*CHB$(252) + 

B=VARPTR(A$) 

C=PEEK( B+2 )*256+ PEEK (B+1 ) 
IF 032767 THEN C=C-65536 
DEFUSH0 = C| '"REM FOR LEVEL - 


CODE 

(60I+CHR$(17>*CHR$(0)+CIIR$(60) 
B$(237)+CHR$(176)+CHR$(33) 
CHR$(32)+CHB$(6)+C!IH$(6ll)+CHR$(119 
CHBM201 ) 

:'POKE 16526 ,PEEK(B+1 ): 'FOR LEVEL 


II 


1100 


: ' POKE 16527 , 


PEEK( B+2) : 'FOR 


LEVEL 


11 


boo 


II 


_ _ DISK BASIC 
LEVEL II BASIC 






600 
700 


X = USH0(0) : 'X=USR(01 : 'FOR 
GOTO 600 


LEVEL II 





Figure 5-5. CHR$ Embedded 
Machine Code 




B = VARPTR (AS! 

B IS SET EQUAL TO 
ADDRESS OF STRING 
"PARAMETER BLOCK" 



LENGTH OF STRING 


B 


MS BYTE OF STRING ADD 


B + 1 


LS BYTE OF STRING ADD 


B + 2 



Figure 5-6. String Parameter 
Block 



Because the string is located in the string storage area 
high in memory, there is a major problem with this 
method! Both Level II and Disk BASIC go through a 
"garbage collection" process when they run out of string 
space. As you recall, a string storage area may be CLEARed 
initially in the BASIC program. 

As operations are performed on strings in the BASIC 
program, the interpreter uses more and more of the string 
storage area. The interpreter is sloppy and does not clean 
up old forms of the strings as new string storage space is 
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allocated. However, after many string operations, the 
interpreter may run out of string storage space and have 
to go back to "clean up" the string storage area. When this 
is done, the memory for the strings are reallocated and the 
string addresses change. 

This garbage collection may never happen in the BASIC 
program you interface to the assembly-language code. It is 
a function of memory size, string storage area, and string 
operations. However, because it can, it is always best to 
find the address of the CHR$ string immediately before 
the machine code in the string is called. 

This method works quite well for short assembly-language 
programs, but one of the limitations is in the length of the 
BASIC line defining the string. To avoid the problem, 
several strings may be concatenated to produce a larger 
string, however, a more stringent limitation is the size of the 
string itself, which cannot be greater than 255 characters. 
You must use all relocatable code in this method. 



DATA Values and Dummy Strings 

A third way to embed assembly-language code in BASIC 
programs is to use a table of DATA values representing 
machine code as in the first method but to move those 
values to a "dummy" string. The advantage of this method 
over the first is that the BASIC program will perform the 
address calculation automatically by the VARPTR function. 
The disadvantages are the string size limitation and the 
requirement of all relocatable code. 

The "dummy string" here is a BASIC string statement of 
the form ZZ$="THIS IS A DUMMY STRING, , . ." The 
number of bytes in the string should be equal to or greater 
than the number of bytes in the assembly-language pro- 
gram. The text is irrelevant. The location of the string is 
found by VARPTR, and the bytes from the DATA table 
replace the characters of the dummy string. 

In this case, reshuffling strings is no problem during the 
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garbage collection process since the string location is in 
the BASIC statement itself and the interpreter records the 
address of the text as the string address. Figure 5-7 
illustrates use of this method with the SCROLL program. 



Hints and Kinks 5-4 

Using Dummy Strings 

There is a slight problem in using a dummy 
string as a storage area for machine code. 
BASIC uses a zero (null) byte to mark the end 
of a text line. If a zero is stored for a byte 
of an instruction, the BASIC interpreter will 
truncate the line during edits, lists, and 
other operations. 

You can store zeroes and use the embedded 
machine language normally. However, don't 
attempt to edit such a program after 
execution . Edit the BASIC program before it ' s 
run and save it on cassette or disk before 
execution. 

If a program is listed after execution, 
strange things will occur as the interpreter 
encounters the modified dummy string. Valid 
machine codes may not be valid display 
characters! 



100 REM DATA TO DUMMY STRING EMBEDDED MACHINE CODE 

200 A$="THIS IS A DUMMY STRING!" 

300 B=VARPTRU$) 

100 C=PEEK(B+2)*256+PEEK(B+1 ) 

500 FOR I=C TO C*22 

600 READ A 

TOO IF I>32767 THEN POKE 1-65536, A ELSE POKE I. A 

800 NEXT I 

900 IF .C>.327_6 7_TK EN DE£UJj_R0 = £r65 5_36_ E_LS_E DEFUS_R0_=C 

100Q~' p'ok"e 16526 ,PEEK(B<-1 ): 'FOB LEVEL II 

1100 ' POKE 16527 ,PEEK(B+2) : 'FOR LEVEL II 

1200 X=USB0(0) ■• ' X=USR(0i i 'FOR LEVEL II 

1300 GOTO 1200 

1H00 DATA 33.61 .60. 17.0,60, 1 , 192, 3.237 , 176,33. 192. 63. 62, 32,6. 6H 

1500 DATA 119,35,16,252.201 

DISK BASIC 

LEVEL II BASIC 



Figure 5-7. DATA to Dummy String 
Embedded Machine Code 
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DATA Values and Array Storage 



By taking advantage of the contiguous nature of arrays, 
you'll have a fourth method of storing machine code within 
the BASIC program. Arrays in BASIC are allocated by DIM 
statements. Once you've established the array, the array is 
treated as a block of data. Any number of bytes can be 
used in the array. The array location remains fixed as long 
as new variables are not referenced; its location can 
always be found by VARPTR. 

Hints and Kinks 5-5 



Array Storage of Machine Code 

If an integer array (such as A%) is used for 
storage of machine code data, remember that 
the elements of the array are two bytes long 
and that the data is stored in normal array 
operations in standard Z-80 address format. 
Storing through 4 in array A%(0)-A%(4) . for 
example, produces 



A%(0) = 
A%(l) = I 
A%(2) = 2 

A%(3) = 3 
A7o W * t 



Take this into account when storing machine 
code data by setting an array element to two 
machine code bytes — 



+0 





+ 1 





+2 


1 


+3 





+1 


2 


+5 





^ 


3 


+7 





+ 8 


4 


+ 9 






A%(4) = (machine code byte n)*256- 
code byte n + 1) 



'machine 
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In this method, the DATA values representing the 
machine code are moved to a dummy array, the VARPTR 
function is used to find the address of the array, and the 
DATA values are moved initially to the array. To make 
storage into the array more straightforward, the array 
should preferably be an array of integer values, since they 
occupy two bytes per element. The elements of an array 
are contiguous, that is, they occupy successive locations 
in memory, and the DATA values can be stored with no 
problem. Figure 5-8 shows this method. 

100 REM DATA TO ARRAY EMBEDDED MACHINE CODE 

200 DIM AJC12) 

300 B=VARPTR(AS!0) ) 

100 FOR 1=0 TO 11 DISKBASIC 

500 READ C, D 

550 E=D»256 + C LEVELII BASIC 

600 IF E>32767 THEN A$ ( I ) =E-65536 ELSE AJ(I)=E 

700 HE XT I 

800 IF B>32762 _THE£ J3EFUSR0 = 8-6 55 3.6 JLSE DEFUSR0=B 

900 - POKE 16526 ,B-IHT(B/256 ) «256 : 'F0R~LCVEL II ~ " 

1000 ' POKE 16527 ,IHT,(B/256) i 'FOR LEVEL II 

1100 X=USR0(0 ) : ' X=0SR(0 i : 'FOR LEVEL II 

1200 GOTO 7100 

1300 DATA 33, 6H ,60 , 17 ,0,60 , 1 , 192, 3,237, 176 ,33, 192.63,62,32,6 ,6H 

1100 DATA 1 19,35 , 16,252 ,201 ,0 



- NOTE DUMMY LAST VALUE FOR EVEN # 



Figure 5-8. DATA to Array 
Embedded Machine Code 

Passing Arguments and 
Multiple Subroutines 

In the above examples, we illustrated the techniques 
with a very simple subroutine. However, you can incor- 
porate all of the material presented in Chapter 4, into 
these embedded machine-language methods including 
passing multiple arguments and multiple subroutines 
back and forth. 

Using embedded machine-language code can be a valu- 
able tool since it blends the easy-to-use string handling, 
display and print formatting, and number-crunching 
abilities of BASIC with the high-speed of assembly lan- 
guage. It's probably well worth your effort to take portions 
of BASIC programs that are notoriously slow and rewrite 
them into short embedded assembly-language routines — 
code such as sorts, searchs, and graphics. Watch for 
further examples of embedded machine-language code in 
later chapters. 

Ill 



SECTION II 

Assembly-Language Techniques 

Chapter Six 
NumberCrunching 

This chapter looks at what is commonly called "number 
crunching." This term refers to operations on data that is 
primarily numeric — adds, subtracts, multiplies, divides, 
trigonometric functions, integration, differentiation, and 
so forth. We only have room here to discuss basic number- 
crunching operations that come up frequently in non-math 
oriented programs — such things as adds, subtracts, 
multiplies, divides, and random number generation. 

Addition and Subtraction 

Addition and subtraction operations are built into the 
instruction set of the Z-80. All other math-related opera- 
tions have to be built out of adds, subtracts, compares, and 
shifts. 

Eight-Bit Adds 

The basic adds and subtracts use two 8-bit operands. One 
of the operands is in the A register, while the other 
operand is either in the instruction itself (immediate 
addressing), in another CPU register (register addressing), 
in a memory location pointed to by the HL register 
(register indirect addressing), or in a memory register 
pointed to by the effective address of an indexed-type 
instruction. 
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Suppose we have 23H in the A register, 45H in the B 
register, 8000H in the HL register pair, 8040H in IX, 7FF0H 
in IY, and 45H in memory location 8000H. All of these adds 
accomplish the same thing, adding a 45H to the 23H in the 
A register, putting the result of 68H in the A register and 
setting the flags. 

1. ADD A,45H Immediate add of45H to 23H in A 

2. ADD A,B Add of 45H in B to 23H in A 

3. ADD A,(HL) Add of 45H in 8000H to 23H in A 

4. ADD A,(IX-40H) Add of 45H in 8000H to 23H in A 

5. ADD A,(IY + 16) Add of 45H in 8000H to 23H in A 

Generally, in arithmetic instructions, all flags are 
affected. But how are the flags set? The C flag is set when 
there is a carry from bit 7 of the result, which does not 
occur here. The Z flag is set when the result is zero, which 
is not the case for the result of 68H. The P/V flag is the 
dual-purpose flag used either for parity or overflow. In 
arithmetic instructions, P/V is always used for overflow. 
There is no overflow here, and P/V is not set. The sign flag 
is set when the result has a one bit in bit 7, indicating that 
the result is negative (not the case here). The N flag is not 
set here since this is an add, and the half-carry flag is not 
set here because there is no carry from bit 3 of the result. 
(N and H are hardly ever used by the programmer, and 
there are no conditional branches on them — so ignore 
them!) 
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Hints and Kinks 6-1 

P/V Flag 

When we talk about parity in the TRS-80 , we're 
not discussing farm prices. Parity refers to a 
count of the number of one bits in (usually) 
an 8-bit location or register. Parity is 
primarily used to check the data on I/O 
operations. Since I/O devices lose data more 
frequently than cpu/memory actions, a check on 
the number of one bits is a rough check on the 
validity of the data. 

In the Z-80, the P/V flag is set for even 
parity . If the number of one bits is even 
after an instruction affecting parity, then 
the P/V flag is set; otherwise it is reset. 
Instructions that set parity in this fashion 
are IN R, (C) , most shifts and rotates, and the 
logical instructions. 

The P/V flag is used for overflow when (most) 
arithmetic instructions are executed. It can 
be tested by a conditional jump to ascertain 
whether or not the result was too large to be 
held as a two's complement number, either for 
8-bit or (some) 16-bit instructions. Overflow 
occurs for 8 bits when a result is below -128 
or above 127 and for 16 bits when a result is 
below -32768 or above 32767. 



Many times an add will be used without any other follow- 
ing action. Sometimes, however, an add will be followed by 
a conditional branch of some type, as in the example from 
the MEMORY Subroutine from Chapter 14 shown in Figure 
6-1. An ADD A,(HL) is done to add the contents of the 
memory location pointed to by HL to the contents of the A 
register. If the result is zero, a conditional jump is made to 
MEM008 to set the count to zero (!); if the result is positive 
(P), a JP is made to MEM010. 
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0013' 


F1 




00320 




POP 


AF 






0011 ' 


F5 




00330 




PUSH 


AF 




0015 ' 


86 




00340 




ADD 


A. ( HL) 


; ADJUST COUNT 


0016 ■ 


CA 


001C 


00350 




JP 


Z.HEH008 


;G0 IF ZERO 


0019 ■ 


F2 


001D" 


00360 




JP 


P, MEMO 10 


iGO IF POSITIVE 


001C 


AF 




00370 


MEH008: 


XOR 


A 


; COUNT OF 


001D' 


FE 


64 


00380 


MEMO 1 : 


CP 


100 




TEST FOR LT 100 


001 F' 


FA 


00211 i 


00390 




JP 


M.MEM020 




GO IF LT 100 


0022 * 


3E 


63 


00400 




LD 


A, 99 




MAX COUNT 


0024 ■ 


T7 




004 10 


MEM020: 


LD 


( H L) , A 




STORE COUNT 



Figure 6-1. Arithmetic Followed 

by Conditional Branch 



Many times programmers get confused about using condi- 
tional branches on flags. Much of the confusion is about 
when the flags get set and reset. Unless an instruction 
description specifically says that the flags are 
affected by the instruction, the flags remain as they 
are! This means that you can use flags from several 
instructions back for conditional branching as long as you 
haven't used instructions that affect the flags in question. 
Many times, however, you will use a conditional JP as the 
next instruction after the arithmetic instruction. 



Eight-Bit Subtracts and Compares 

Eight-bit subtract instructions operate in the same 
addressing modes as the ADD instruction. The flags are set 
in almost identical fashion, with a few exceptions. The SUB 
sets the C flag if there is no borrow. This means, in fact, 
that the C flag is reset if there's a carry out of bit 7 — just 
the reverse of the ADD! 
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'Hints and Kinks 6-2 

Carries 

When is a carry set, and when is it reset on an 
add, subtract, or compare? Here's how you can 
find out manually: If an add is being 
performed, add the two operands in binary; any 
carry bit out of the high order will simply 
set the carry. 

On a subtract or compare, convert the two 
operands to binary. Now take the two' s 
complement of the subtrahend ( the one to be 
subtracted). Now add the operands. Complement 
the state of the carry. The result will be the 
state of the carry after a subtract or 
compare. After running through several 
thousand test cases, we discovered that the 
carry was set on a subtract or compare if a 
larger unsigned number was subtracted from a 
smaller unsigned number. What about signed 
numbers? This will be left as an exercise for 
those readers who are not faint of heart 



I 



000000 I 1 3 
00000010 -(+£) 

I I I I I I 10 2'SCOrtP 
■ 0000000 \ + 1 RESULT 



0- 

i 

i 



00000010 2 

00000011 -(f3) 

i I M 1 1 I 2'S COM P 
I I I II II I -I RESULT 



I 11 i I 1 10 25", 

1 I I I I I 11 -(+255) 

CY 00000001 2'5COM P 

-*- II I I I I 1 1 - 1 RESULT 

+ 
I 
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You would think that adding -5 to 10 in A would be the 
same as subtracting 5 from 10 in A. However, it isn't, as 
the C is set for the ADD and reset for the SUB. (Also, the N 
and H flag logic is different for the ADD and SUB.) The 
result in A is still the same. 



LD A ,10 
ADD At-5 
JP C»0UT 



ilO TO A 

5 10 PLUS -5 TO A 

5THIS JUMP IS MADE 



LD 


A , 1 


5 10 TO A 


SUB 


A ,5 


5 10 MINUS 5 TO A 


JP 


C ,QUT 


5THIS JUMP IS NOT 



MADE 

Compares operate in identical fashion to subtracts, except 
that the result is thrown away and is only used to set or 
reset the flags. Figure 6-2 shows use of the SUB and CP 
from the DECBIN subroutine of Chapter 13. 



JUMP IF A NOW 
HOLDS MINUS NUMBER 
(IF A WAS LESS THAN 
30HI 



JUMPIF|AI=>10 



5A3 7E 


09160 \ 


LD 


A,(HL) / 


GET CHARACTER 


5A4 D630 


09170 * 


SUB 


30H / 


CONVEBI 


5A6 FAB685 


091 80 


JP 


M.DEC070 | / 


00 IF LT "0" 


5A9 FEOA 


09190 


CP 


10 f 


TEST FOB GT "9 


5AB F2B685 


09200 


JP 


P.DEC070 1 


GO IF GT "9" 


5AE 5F 


09210 


LD 


E, A 


NOW IN E 


5AF 1600 


09220 


LD 


D,0 


NOW IN DE 


5B1 DD19 


09230 


ADD 


IX, DE 


MERGE 


5B3 23 


09210 


INC 


HL 




5B1 10E2 


09250 


DJNZ 


DEC040 


GO IF MORE 


5B6 78 


09260 DEC070 


LD 


A.B ;C( 


)UNT TO A 



Figure 6-2. Use of SUB and CP 
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Sixteen-Bit Adds and Subtracts 

Sixteen bit adds and subtracts can use either HL, IX, or IY 
as 16-bit accumulators similar to the A register. How- 
ever, the number of addressing modes that can be used for 
register pairs is limited to one, the one associated with 
adding another register pair to HL, IX, or IY. Also, while 
you can do an ADD or ADC to HL, IX, or IY, you aren't allowed a 
SUB or SBC for IX or IY. 

Another difference in the 16-bit arithmetic instructions is 
that the flags may or may not be affected, according to 
the instruction. ADD HL,BC, for example, does not affect Z, 
P/V, or S, while ADC HL.BC does affect these flags. To see 
which flags are affected keep one eye on Appendix II while 
using these instructions with conditional JPs. 

Figure 6-3 shows you a trick to use with the C flag. The 
ADD HL,DE does not affect the Z flag, but does affect the C 
flag. In this subroutine, the programmer did a decrement 
on the contents of HL by loading DE with -1 and performing 
the ADD HL,DE. The C flag will be set as long as HL is 
positive or zero, but will be reset when HL reaches -1. 
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Both the 8-bit and 16-bit adds and subtracts have 
instructions that add or subtract the carry (or borrow). 
ADC A,23H, for example, adds not only 23H to the contents 
of A, but also the current state of the carry. SBC HL,BC 
subtracts not only BC from HL, but also subtracts the 
carry. 
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These instructions are used primarily for multiple-pre- 
cision operations involving more than 8 or 16 bits of data. 
The carry or borrow must be propagated from the lower 
order to the higher order byte or "word." 



■Hints and Kinks 6-3 



Multiple-Precision Operations 

How far can multiple-precision operations be 
carried out? It's entirely possible to 
implement arithmetic that works with 100 bytes 
of precision. The question is, is it 
necessary? To get a rough idea of the number 
of decimal digits that can be contained in any 
size binary number, take the number of bits 
and divide by 3,5 - 8 bits would be 2.3, 16 
bits would be 4.5, 32 bits would be 9.1, and 
so forth (4.5, for example, would be somewhere 
between four and five decimal digits). You can 
see it doesn't take too many bits before we 
can express ten or twenty decimal digits of 
precision. 

Aside from mathematical games or precise 
scientific applications, there's generally no 
need for large multiple-precision numbers. The 
compromise reached in all computers is to hold 
floating-point numbers with a dozen or so 
decimal digits precision and an exponent that 
represents a power of 16. This format would 
still call for multiple-precision operations 
on the ' 'fractional' ' part, but it would be 
limited to operations involving approximately 
3 to 6 bytes. 

Even with a small number of bytes, 
multiple-precision multiplies and divides are 
tedious and slow. Rather than writing a 
bit-by-bit divide to work with 64 bits, many 
programmers would implement something like 
this: A four-byte number can be expressed as 
AB*16 2 + CD, where A, B, C, and D are the byte 
values. To multiply two such numbers in 
four-byte precision would involve the 
expansion — 
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ABCD*EFGH = AB*EF + 


CD*EF + AB*GH + 


CD*GH 




This would require four 16-bi 


t multiplies, 


considerable multiple-precision shifting, and 


four multiple-precision adds 


This is a lot of 


work for assembly-language programmers, who are 


notorious for looking for the easy way out! 



Figure 6-4 shows a use of this in the SUB subroutine from 
Chapter 13. SUB subtracts the contents of a four-byte 
variable SEED through SEED + 3 from the contents of DE,HL. 
DE,HL are treated as a four-byte variable. Note that ini- 
tially the carry is cleared by an OR A instruction. One of 
the peculiarities of the Z-80 is that it has a SCF to set the 
carry, and a CCF to complement the carry, but no Reset 
Carry; the OR A does reset the C flag, however, and the 
contents of A remain unchanged. The next SBC is not 
preceded by an OR A to reset the carry, and the carry from 
the first SBC is subtracted from the result. 



08600 
08610 
08620 
08630 
086HO 
08650 
08660 

8571 C5 08670 SUB 

8572 EDHBE385 08680 

8576 B7 08690 

8577 EDH2 08700 

8579 EB 08710 
857A EDHBE185 08720 
857E EDH2 08730 

8580 EB 08710 

8581 CI 08750 

8582 C9 08760 



RESETS CARRY 
FOR FIRST 
SUBTRACT 



BsH«fflSflaB«sfiBfifiBsuBTRACT SEED SUBROUTINE* 6 ******' 1 ** 11 8 

» SUBTRACTS FOUR BYTES OF SEED FROM (DE.HL). 

• ENTRY: (SEED - SEED+3)=SEED I 

» (DE,HL)=FOUR-BYTE VALUE 

» EXIT: (DE,HL)=RESULT OF SUBTRACT 

» ALL REGISTERS SAVED EXCEPT DE.HL 



BC 

BC, (SEED+2) 




DE.HL 
BC 



CARRY 

CONTAINS RESULTS 

OF FIRST SUBTRACT 



SAVE REGISTERS 

GET LS BYTE 

RESET CARRY 

SUBTRACT LS 2 BYTES 

GET MS 2 BYTES 

GET MS 2 BYTES 

SUBTRACT MS 2 BYTES AND CY 

NOW ORIGINAL-SEED 

RESTORE REGISTERS 

RETURN 



Figure 6-4. Four-Byte Subtract 

Example 
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Multiplies and Divides 

All multiplies and divides on the Z-80 must be performed 
in software. There are a number of methods for per- 
forming software multiply and divides, ranging from suc- 
cessive addition and subtraction to high-speed table 
lookups. We'll discuss some of the more common ways 
here. 

Software Multiplies 
Successive Addition 

The simpliest multiply is by successive addition, as 

shown in Figure 6-5 from Chapter 13. Here, the DE 
register contains the multiplicand and is added to HL 
(after HL is cleared) a number of times corresponding to 
the multiplier. Three adds are used to multiply by three. 



1 C9 


ED53E585 02560 


LD 


(D0T0) ,DE 


;ST0HE DOT ON TIME 


1CD 


210000 


025T0 


LD 


HL,0 




1D0 


19 


02580 


ADD 


HL.DE 


;FIND 3"D0T0 


1D1 


19 


02590 


ADD 


HL.DE 




1D2 


19 


02600 


ADD 


HL.DE 




1D3 


22ET85 


26 1-0 


LD 


(DASHO) , HL 


; STORE DASH ON TIKE 



Figure 6-5. Multiply by 
Successive Addition 



A variation on this approach uses the multiplier in the B 
register to take advantage of the DJNZ instruction. 



MULT 



LOOP 



LD 


B » 1 


5MULTIPLIER =10 


LD 


DE >34 


5ARBRITRARY MULT IP 


LD 


HL »0 


5CLEAR RESULT 


ADD 


HL »DE 


5SUCCESSIYE ADD 


DJNZ 


LOOP 


5G0 IF NOT N TIMES 



ICAND 
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Shift and Add Multiply 

Another type of multiply is the "shift and add." This 
method, as the name implies, is a combination of shifts 
and adds. You can factor any multiplier into a number of 
powers of two factors. You can multiply N by 20, for 
example, by adding 16*N + 4*N. Sixteen and 4 are powers 
of 2 that you can easily obtain by shifting. 

This type of multiply works best for commonly used 
multipliers, like 10. The code in Figure 6-6 below, 
excerpted from the Decimal to Binary Conversion 
subroutine of Chapter 13, shows how you can use this 
method. The number is shifted by an ADD DUX, which 
shifts the number one bit position left. Four shifts result in 
N*8. The previously saved N*2 shift is then "popped" into 
DE and added in to give N* 10. 









TIMES 2 SAVED IN STACK 




598 DD29 
59A DDES 
59C DD29 
59E DD29 
5A0 D1 
5A1 DD19 


09100 
091 10 
09120 
09130 
091H0 
09150 


DEC0140 \( ADD 

1 PUSH 

ADD 

ADD 

1 POP 

i ADD 


IX, IX 
IX 1 
IX, IX 
IX, IX 
DE | 
IX, DE 


INTERMEDIATED 

•U 
•8 
•2 
•10 








TIMES 2 RETRIEVED 
FROM STACK 








F 


igure 6-6. Shift and Ad< 


i 










Example 





In the multiplies above, you'll have speed limitations in 
the successive addition case (for large multipliers, the 
process takes a very long time) and lack of generality in 
the shift and add case. For programs that perform many 
multiplies of different sizes of numbers, it's best to 
implement a bit-by-bit multiplication. 

Bit-By-Bit Multiply 

A bit-by-bit multiply, implemented as a subroutine, is 
presented in Figure 6-7. The multiplier is held in DE on 
entry and the multiplicand is in BC. On exit, the result is 
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held in DE, HL, treated as a four-byte register. If the 
product of the multiply is less than 65536, then it is in HL 
alone with zero in DE. 



8000 




00050 




ORG 


8000H 








00100 


!««»«* 


iflllli 


i«i«»***s*»« 


iiiiiiiiiiiiiliii>i«iittitiiif 






001 10 






SWEET 16 


MULTIPLY 






00120 


» ENTRY: (DE) 


=HULTIPLIER, 


16 BITS UNSIGNED 






00130 




(BO 


^MULTIPLICAND, 16 BITS UNSIGNED 






00140 


* EXIT 


(DE, 


HL)=PRODUCT. 


32 BITS UNSIGNED 






00150 




(BO 


=RETAINED 








00160 




(A) = 


DEVASTATED 








00170 




EVERYTHING ELSE 


IN REASONABLE ORDER 






001 80 


» HISTORICAL 


NOTES: THIS 


MULTIPLY WAS WRITTEN WHILE 






00190 


« PULLING TOGETHER THE 


FINAL PIECES OF THIS BOOK 






00200 


« IN 


ABOUT 


23577 MILLISECONDS. (NO, NOT THE 1ST TIME). 






00210 


t«««**«««ttC*f«ft*tftft«i«»tl 


ftlllllllllllHillHIfllllllll 






00220 










8000 


210000 


00230 


3WE16 


LD 


HL,0 


;ZER0 PRODUCT HALF 


8003 


3E10 


00240 




LD 


A, 16 


; ITERATION COUNT 


8005 


EB 


00250 


SWE010 


EX 


DE, HL 


; SETUP FOR SHIFT 


8006 


29 


00260 




ADD 


HL.HL 


; SHIFT DE 


8007 


F5 


00270 




PUSH 


AF 


iSAVE POSSIBLE CARRY 


8008 


EB 


00280 




EX 


DE.HL 


iPUT DE BACK 


8009 


29 


00290 




ADD 


HL.HL 


;N0W BOTTOM HALF 


800A 


3001 


00300 




JR 


NC.SWE020 


;GO IF NO CARRY 


800C 


13 


00310 




INC 


DE 


;PROPOGATE 


800D 


F1 


00320 


SWE020 


POP 


AF 


;GET C FROM DE 


800E 


3004 


00330 




JR 


NC.SWE030 


;GO IF NONE 


8010 


09 


00340 




ADD 


HL.BC 


;BIT WAS A ONE 


801 1 


3001 


00342 




JR 


NOSWE030 


;GO IF NO CARRY TO MSB 


8013 


13 


00344 




INC 


DE 


;PR0P0GATE 


8011 


3D 


00350 


SWE030 


DEC 


A 


; DECREMENT COUNT 


8015 


20EE 


00360 




JR 


NZ.SWE010 


;GO IF MORE 


8017 


C9 


00370 




RET 




;BACK TO CALLING PROG 


0000 




00380 




END 






00000 TOTAL 


ERRORS 











Figure 6-7. Bit-by-Bit Multiply 
Code 



The subroutine works by shifting DE, HL. The bit shifted 
out of DE is used to determine whether you should perform 
an add of BC to HL. HL holds the partial product. Sixteen 
shifts are performed, and each one causes either an add or 
no action dependent upon whether the carry is a one or 
zero. The action of the multiply is shown in Figure 6-8. 
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•Hints and Kinks 6-4- 
Fast Multiplies 



It seems that computers are constantly being 
pushed by the applications! By that I mean 
that there's a constant requirement for faster 
and more efficient computers to handle 
applications that haven't been computerized 
and could be, or to speed up existing 
applications , 

One of the critical areas of application 
involves multiplies as they are used in all 
kinds of number crunching. Since we don't have 
a hardware multiply on the TRS-80 , we have to 
make do with a software routine. 

You can speed up multiplies considerably by 
making them ''in-line' 1 code. This method 
eliminates the usual 8- or 16-iteration loop 
by substituting 8 or 16 code segments. 
Multiplies of 150 microseconds for 8 bits are 
possible with this approach, a factor of two 
better than some iterative multiplies. 

Other high-speed multiplies involve 
constructing large tables of partial results 
for various multiplier/multiplicand 
combinations . 




CY BIT SET IF 

MULTIPLIER BIT =1 

RESET IF MULTIPLIER BIT = 8 



r\ 



H 



SHIFT DE.HL 
LEFT ON EACH 
OF 16 ITERATIONS 



MULTIPLIER. (INITIALLY) 



PARTIAL PRODUCT 



it 



MULTIPLICAND 
1 



ADD MULTIPLICAND TO 
PARTIAL PRODUCT IF 
MULTIPLIER BIT IN CY 
IS 1, OTHERWISE DO 
NOT ADD FOR THE 
ITERATION 
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Figure 6-8. Bit-by-Bit Multiply 
Action 



Software Divides 
Successive Subtract Method 

Software divides are handled in similar fashion to 
multiplies. Figure 6-9 shows a successive subtract method 
from the code of Chapter 13. It divides a 16-bit dividend in 
HL by a 16-bit divisor in BC. Each time the divisor is 
successfully subtracted from the dividend without 
producing a negative result (no carry), a count in DE is 
incremented by one. The count was initially set to -1. At 
the end of the divide, DE holds the count, which is the 
quotient. You could find the remainder by adding BC back 
to the residue in HL, although this is not done in the code. 









HL 

i 










DE 

t 








DIVIDEND 




QUOTIENT 






I' 

SBC, HL 

1 


, BC 








{ 






DIVISOR 




INCREMENTED BY 
1 FOR EACH SUC- 








i 












SC 






CESSFUL SUBTRACT 


1BA 


21C003 


02480 




LD 


HL.SPEEDF 


;1200/WPM=D0T0 TIME 


1BD 


14F 


02490 




LD 


C, A 


;HPM LS BYTE 


1BE 


0600 


02500 




LD 


B, 


;N0W IN BC 


ICO 


11FFFF 


02510 




LD 


DE.-1 


:QUOTIENT 


1C3 


B7 


02520 


SPE015 


OR 


A 




ZEB0 C 


1C« 


EDH2 


02530 




SBC 


HL.BC 




DIVIDE BY SUCCESSIVE SU 


1C6 


13 


02510 




INC 


DE 




BUMP QUOTIENT 


1C7 


30FA 


02550 




JH 


NC, SFE015 




GO IF NOT NEGATIVE 


1C9 


ED53E585 


02560 




LD 


( 


DOT 


31 ,DE 


;S] 


'ORE DOT ON 


TIME 



Figure 6-9. Divide by Successive 
Subtraction 



Bit-By-Bit Restoring Method 

Another type of divide is implemented in the code from 
Chapter 14 shown in Figure 6-10. This is a bit-by-bit 
"restoring" divide, which divides the 16-bit dividend in HL 
by an 8-bit divisor in E. On exit, HL holds the quotient and 
BC holds a remainder. The action of the divide is shown in 
Figure 6-11. 
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,x 



QUOTIENT BIT 
9 IF SBC HL.DE 
CY BIT SET IF RESULT - RESULT WAS - 

RESET IF RESULT + , | F SBC HLDE ' 

RESULT WAS + 



I 



CY^ H L IX 

I £2S L_ 



^— 



ZEROES (INITIALLY) 

i 



DIVISOR (INITIALLY) 



ft 



SHIFT HL.IX 
LEFT ON EACH 
ITERATION 



<&0 m 00 00 DIVIDEND 



D 



SUBTRACT DE 
FROM HL ON 
EACH ITERATION 
ADD BACK IF 
RESULT NEGATIVE 



Figure 6-11. Bit-by-Bit Divide 
Action 



Signed Vs. Unsigned Multiplies and 
Divides 

All of the multiplies and divides we've discussed above 
were unsigned. That is, all operands were considered to 
be positive numbers with no sign bits. This means that the 
range of numbers held in a 16-bit result would be 
through 65535, rather than -32768 through +32767. 

You may wonder if a signed multiply or divide is possible. 
Yes, but the rules for a signed operation are somewhat 
sticky. It is best to find the absolute value of the 
operands, perform the unsigned multiply and divide, and 
then convert the result to the proper sign. 

Overflow Limits 

Another problem that we haven't discussed in the above 
code is overflow. Overflow may occur when the register(s) 
dedicated to the product or quotient is not large enough to 
hold the largest possible case. 
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For an unsigned multiply, overflow can occur if the results 
registers do not hold at least a number of bytes equal to 
the total number of bytes in the multiplicand and 
multiplier. For example, a multiply of a one-byte number 
by a two-byte number may produce a three-byte result 
(but not greater than three bytes). 

For an unsigned divide, overflow may occur if the 
register(s) dedicated to the quotient is not equal to or 
greater than the number of bytes in the dividend. The 
worst case here is the divide-by-one case. Divide-by-zero is 
not a legitimate operation and will result in a quotient of 
all ones. 

How do you detect overflow? Not by the P/V flag, which is 
usually unrelated to the multiply or divide actions! You 
must know the ranges of the numbers you'll be dealing 
with beforehand or be certain by testing the operands that 
no multiply or divide operation will cause overflow. 

Random Number Generation 

Many times it's necessary to generate "random" numbers. 
The uses for random numbers ranges from simple 
applications such as determining whether a plague will 
strike in "Hammurabi," to more complex simulation and 
modeling. 

There are really two types of "random" numbers — 
pseudo-random numbers and true random numbers. True 
random numbers aren't predictable, but pseudo-random 
numbers are. 

True Random Numbers 

An example of a true random number generation occurs 
when a (perfect) die is rolled or when a (perfect) coin is 
flipped. The next toss of the die or flip of the coin is 
completely unpredictable. Over the long run the 
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distribution of the points coming up on the die will 
approach an even number of ones, twos, threes, fours, 
fives, and sixes, and there will be close to an equal number 
of heads and tails for the coin flip. 

Can we get a true random number on the TRS-80? The 
answer is a qualified yes. One way to get a 7-bit random 
number is to read the contents of the R register in the 
Z-80. The R register refreshes the dynamic memories by 
counting from to 127 and then recycling. If an external 
event occurs at irregular intervals that are very large 
compared to the R register counting, a true random 
number is obtained. 

One such external event is a keypress. If we look at R at 
every keypress, we can obtain a good random number from 
through 127. The code for such an operation looks for a 
keypress and then reads R into the A register. 

READ CALL INPUT JREAD KEYBOARD 

JR Z»READ 5GQ IF NO KEYPRESS 

LD A»R 5N0W HAVE RANDOM 
* 0-127 IN A 



Pseudo-Random Numbers 

A pseudo-random number is predictable. As a matter of 
fact, it's convenient to have code that will start from a 
given "seed" value and generate a whole string of numbers 
without repeating each time we start from the same seed. 
If we have such a routine, we can still get a good 
distribution of all numbers over the range and repeat the 
sequence any time we wish. 
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■Hints and Kinks 6-5 



Random Number Problems 

One of the main rules in random number 
generation is this: Never use any old 
algorithm to generate what you think will be a 
string of random numbers. If you take the 
contents of HL, multiply by your Social 
Security number, and add your best 10 
kilometer running time to produce a series of 
pseudo-random numbers, you're almost 
guaranteed of producing a series that 
' 'decays' ' down to 18766 after 32 numbers have 
been produced. It's best to consult a good 
programming text for some tried and true 
algorithms. Even there, you'll find vehement 
disagreement among computer scientists about 
which methods are the best. (Personally, I 
take my wife's Social Security number . . . .) 



One of the common algorithms for generating random 
numbers is to multiply an odd power of five times the seed 
value. The multiply produces a 16-bit or greater product 
(whatever we care to make it). When overflow results, the 
product represents the remainder of a 64K (for 16 bits), 
with the divide due to the length of the register. This 
divide is called a modulus operation. The product is the 
next pseudo-random number, and the process is repeated 
indefinitely. The greater the length of the register holding 
the product, the longer the cycle before the pseudo- 
random number sequence repeats. For 32 bits, the cycle is 
millions of numbers. 

Two pseudo-random sequences are used in the codes of 
Chapters 13 and 14. They're basically the same. One is 
shown in Figure 6-12. 
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Pseudo-Random Number 

Routine 
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The RAND routine performs a shift and subtract of the 
four-byte SEED value. Seven shifts of SEED in DE, HL are 
done by calling the SHIFT subroutine. This multiplies the 
old seed by 128. Then the old SEED is subtracted three 
times from the shift result to give SEED*125. The new seed 
is stored into SEED for the generation of the next pseudo- 
random number. 



Towards Infinite Precision 

A frequent question in assembly language is how to handle 
large numbers. Multiple-precision adds and subtracts are 
relatively easy to implement (by using ADC and SBC 
instructions), but multiplies and divides of many bytes are 
tedious to code. 

When the range of numbers is very great, a better 
approach is to implement floating-point processing in the 
assembly language. Floating-point holds numbers in a 
scientific-notation format geared to microcomputers (see 
Figure 6-13). Unfortunately, the implementation of this 
code for such processing is fairly complex. 



SIGN OF FRACTION 



f\ 


BYTE0 


BYTE1 


+• 


EXPONENT 
1 POWER, OF lb 
(EXCESS toH CODE ) 


FRACTION 
MS BYTE 


FRACTION 
NEXT SIG. BYTE 


FRACTION 
LS BYTE 



BYTE 2 



BYTE 3 



Figure 6-13. Floating-Point Number 
Representation (Typical) 

Disk Editor/Assembler users have the arithmetic rou- 
tines of the Disk Editor/Assembler library available to 
them to perform addition, subtraction, multiplication, 
division, and exponentiation of both integer and real 
(floating-point) numbers. The Disk Editor/Assembler 
manual describes the ways to use these options, but their 
use basically involves setting up arguments for the func- 
tion registers and then referencing the library routine by a 
CALL. The library routine is then automatically loaded at 
load time by the Disk Editor/Assembler Loader. 
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Chapter Seven 
Working With Character Data 

Assembly-language routines to generate and process ASCII 
character data are our topics for this chapter. The first of 
these routines is the procedure for reading ASCII 
characters from the TRS-80 keyboard. Although ROM 
routines can be used, constructing your own keyboard 
scanning and conversion routines are not difficult and 
offer a lot of versatility. 

Other common character-processing routines found in 
assembly-language programs are string input routines to 
read in user character strings, message output routines to 
display messages on the screen, character output routines 
to echo input characters, and routines to convert between 
binary data and ASCII decimal strings. 

We'll get to all of these routines in this chapter, paying 
close attention to the keyboard scanning process and 
conversion to ASCII. 

Keyboard Operation and Scanning 

There are built-in routines in Level II BASIC and Disk 
BASIC to read the keyboard and convert a keypress into a 
character. The addresses and calls are documented in 
other Radio Shack literature. However, we can bypass 
these and read the keyboard directly. In doing so, we can 
make the routine as versatile as we want by making the 
keys represent any character or function! 

The keyboard is really a matrix of switches as shown in 
Figure 7-1. There's nothing magical about its operation. 
Pressing a key simply connects a column line and a row 
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line together for as long as the key is held down. There's a 
certain amount of keybounce associated with the con- 
nection. If we could observe the connection from a micro- 
scopic scale in slow motion, we'd see a definite "make- 
break-make ..." before the connection was firmly estab- 
lished. The same thing would happen when the key was 
released. This process is shown in Figure 7-2. 
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Figure 7-1. TRS-80 Model ! 

Keyboard Configuration 

(Upper Case) 
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TYPICALLY 
20-50 MS. 



KEYBOUNCE 
ON MAKE 



\ 



/ 



KEYBOUNCE 
ON BREAK 



Figure 7-2. Keyboard Bounce 



Our job, and it's fairly simple, is to convert a switch 
connection defined by a row, column into an ASCII char- 
acter and to debounce the contact to avoid reading the 
same key many times. 



Scanning 

Each of the eight rows is addressed by a unique address, as 
shown in Figure 7-1. The address of the first row is 3801H, 
the second 3802H, the third 3804H, the fourth 3808H, the 
fifth 3810H, the sixth 3820H, the seventh 3840H, and the last 
3880H. How do we address the rows? By simply doing a 
"load" from the memory location representing the row. To 
address the third row, we'd do 

READ LD A»<3B04H> 1READ KEYBOARD ROW 2 
Here, we've called the row "row 2", as we counted from 
"row 0". 

When the LD is executed, the A register is loaded with a 
byte that represents the state of the column lines at that 
instant in time. A column line will hold a one bit if a key 
along the addressed row is being held down. If more 
than one key along that row is being held down, there will 
be several one bits. Note that the keys associated with 
other rows are not detected at all. 
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The process of addressing eight rows, one at a time, and 
looking for a one bit representing a keypress is called 
keyboard scanning. Since an LD instruction takes about 
8 microseconds (8 millionths of a second), you can do this 
keyboard scan very quickly relative to a keypress. You 
might hold down the typical key for 50 milliseconds or so, 
representing the time of 250 complete scans! 

The processing for detecting any keypress, then, is really 
very simple and goes something like this: 

1. Read row 0, address 3801H. Look for a non-zero value. 
If zero, go on else go to step 9. 

2. Read row 1, address 3802H. Look for a non-zero value. 
If zero, go on else go to step 9. 

3. Read row 2, address 3804H. Look for a non-zero value. 
If zero, go on else go to step 9. 



7. Read row 6, address 3840H. Look for a non-zero value. 
If zero, go on else go to step 9. 

8. Scan complete and no key press. Go back to step 1. 

9. Keypress here. Row number is known. Find column 
number by finding which bit of the eight columns is a 
one. Read the state of row 7, the SHIFT key and record it 
if necessary. Convert the key to ASCII or another code 
and take action on it. 

Conversion 

When the keyboard scan detects a non-zero value in any 
row, the next step to perform is conversion of the row, 
column representation into ASCII or some similar code. For 
example, the intersection of row 2, column (bit) 3 is asso- 
ciated with the key marked B on the keyboard. 

The usual conversion of this key will, of course, be to an 
ASCII S, or 53H. There's no reason, however, that you can't 
convert this key to a code that means "scroll up," "insert," 
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"get the next disk sector," or anything else you want. The 
point is that the conversion routine simply converts one of 
53 keys to any value the programmer wants. Usually 
these values are ASCII. 

The algorithm for the conversion is this: 

1. Take the least significant byte of the row value — 
1,2,4,8,16,32, or 64. Convert to the row number of 
0,1,2,3,4,5, or 6. 

2. Multiply the row number by 8. We now have 0,8,16, 
24,32,40, or 48. 

3. Add in the column bit number of through 7. We 
now have a unique value from through 55, represent- 
ing the key that has been pressed. 

4. If the SHIFT key is to be used, add if no SHIFT or 56 
if shift. We now have a unique value of through 111 
representing the key that has been pressed and the 
"upper-" or "lower-case" status. 

5. Use the value obtained above to get one of 56 or 112 
bytes from a keyboard conversion table. The byte ob- 
tained will be the ASCII value of the key, or whatever 
code we want to use for the key. 







- Hints and Kinks 7-1 — 
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Debouncing 

Debouncing is necessary because of the high speed of 
keyboard scanning. If we scanned the keyboard, converted 
a key, stored the value, and then came back to repeat the 
process for the next key, we'd probably be able to start the 
next scan after 200 microseconds. Since the typical key is 
held down for 50 milliseconds, we'd pick up the key 250 
times again! 

We need to delay a certain amount of time after we first 
detect and process the key. This delay will be long enough 
so that the key is released in the interim. If we are 
speaking of average typing speeds of 40 words per minute, 
the number of characters per second are about 4 or less. 
This is one every 250 milliseconds or so. Delaying 100 
milliseconds then, should more than handle average typ- 
ing speeds and yet bypass the period during which the key 
is held down. 



Hints and Kinks 7-2 

' 'Auto' ' Key 

One of the easier things to implement in an 
assembly-language keyboard routine is an 
' 'automatic' ' key function. If you hold the 
key longer than the 100 millisecond delay, it 
is reread. This results in an ''auto'' key 
function for any key, which will operate at 10 
characters/second. 



There are more sophisticated keyboard decoding routines 
that handle "n-key rollover" in which you can press a new 
key while you are still holding the old, but the delay 
technique above is fine for most processing. 

A Typical Keyboard Subroutine 

We now have all the elements we need to read and convert 
the keyboard. Figure 7-3 shows a complete subroutine that 
will perform the task. 
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FOOO 




00100 




ORG 


OFOOOH 










001 10 


;«»••«»••««•»»•»•»«•«••«»»«•««»•«••«««««•«»«»»»»»•«••««»« 






00120 


; * 




READ KEYBOARD ROUTINE * 






00130 


;« ENTRY: NO 


PARAMETERS 


* 






00140 


;» EXIT: (A) 


= KEY CONVERTED TO KBLUT VALUE • 






00150 


> * 




OR ZERO IF NO KEY HAS BEEN PRESSED • 






00160 


> iifRitimif 


i«(ltiit>f)litlllll*ixtflliliiit(llllifl«f*l 






00170 


; 












00180 


; SCAN 


SEVEN 


ROWS 




FOOO 


210138 


00190 


READKB 


LD 


HL.3801H ; 


ROW ADDRESS 


F003 


7E 


00200 


REA010 


LD 


A,(HLi 


;GET ROW VALUE 


fooi 


B7 


00210 




OR 


A 


;TEST FOR ZERO 


FC05 


2005 


00220 




JR 


HZ, REA020 


;G0 IF KEY THERE 


F0 07 


CD25 


00230 




SLA 


L 


;SHIFT ROW ADDRESS 


F009 


F8 


00240 




RET 


M 


:G0 IF LAST ROW, NO PRESS 


FOOA 


18F7 


00250 




JR 


REA010 


:MORE ROWS TO GO 






00260 


; CONVERT ROW 


, COLUMN TO INDEX 




FOOC 


4F 


00270 


REA020 


LD 


C,A : 


ROW VALUE 


FOOD 


AF 


00280 




XOR 


A ; 


ZERO A 


FOOE 


CB3D 


00290 


REA025 


SRL 


L 




SHIFT ADDRESS 


F010 


3801 


00300 




JR 


C, REA035 




GO IF DONE 


F012 


C608 


00310 


REA030 


ADD 


A, 8 




R0W«8 


F01D 


18F8 


00320 




JR 


REA025 




CONTINUE 


F016 


06FF 


00330 


REA035 


LD 


B.OFFH 


COLUMN COUNT 


FOie 


on 


00310 


REA040 


INC 


B 




BUMP COUNT 


F019 


CB39 


00350 




SRL 


C 




SHIFT ROW VALUE 


F01E 


30FB 


00360 




JR 


NC, REA040 




CONTINUE TILL "1" OUT 


FOID 


80 


00370 




ADD 


A,B 


NOW R0W«8+C0L IN A 


FOIE 


4F 


00380 




.LD 


C, A 


TRANSFER TO C 






00390 


; FIND 


TABLE 


ENTRY 




F01F 


3A8038 


00400 




LD 


A, (3880H) 


SHIFT ROW ADDRESS 


F022 


B7 


004 10 




OR 


A 


TEST FOR SHIFT 


F023 


2802 


00420 




JR 


Z.REA045 


GO IF NONE 


F025 


3E38 


00430 




LD 


A, 56 




F027 


81 


00410 


REA015 


ADD 


A,C 


ADD HASH+SHIFT»56 


F0 2-8 


(IF 


00450 




LD 


C.A 


NOW ROW»8+COL«SHIFT«56 


F029 


0600 


00460 




LD 


B, 


NOW IN BC 


F02B 


213AF0 


00470 




LD 


HL, KBLUT 


ADDRESS OF LOOK UP TABLE 


F02E 


09 


00480 




ADD 


HL.BC 


POINT TO CODE 


F02F 


7E 


00490 




LD 


A,(HL) 


GET VALUE 






00500 


; DEBOUNCE DELAY 




F030 


210021 


00510 




LD 


HL.8448 


100 MS DELAY 


F033 


01FFFF 


00520 




LD 


BC.-1 


DECREMENT 


F036 


09 


00530 


REA050 


ADD 


HL.BC 


; DECREMENT COUNT 


F037 


38FD 


00510 




JR 


C.REA050 


:G0 IF NOT DONE 


F039 


C9 


00550 




RET 




RETURN WITH CODE IN A 






00560 


; LOOK 


UP TABLE 




0008 




00570 


KBLUT 


DEFS 


8 


ROW LC 


0008 




00580 




DEFS 


8 


ROW 1 LC 


0008 




00590 




DEFS 


8 


ROW 2 LC 


0008 




00600 




DEFS 


8 


ROW 3 LC 


0008 




00610 




DEFS 


8 


ROW 4 LC 


0008 




00620 




DEFS 


8 


ROW 5 LC 


0008 




00630 




DEFS 


8 


,ROW 6 LC 


0008 




00610 




DEFS 


8 


SOW UC 


0008 




00650 




DEFS 


8 


,R0W 1 UC 


0008 




00660 




DEFS 


S 


ROW 2 UC 


0008 




00670 




DEFS 


8 


, ROW 3 UC 


0008 




00680 




DEFS 


8 


;ROW 4 UC 


0008 




006 90 




DEFS 


8 


;ROW 5 UC 


0008 




00700 




DEFS 


8 


;ROW 6 UC 


0000 




00710 




END 






00000 TOTAL 


ERRORS 













Figure 7-3. 

Keyboard Read 

Routine 
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The subroutine is divided into scanning, converting to an 
index value, finding the lookup table value, and 
debounce delay. 

The scanning cycles through the addresses of 3801H 
through 3840H. HL is initialized with 3801H. Thereafter, 
only L is shifted left to get the "02H", "04H", etc. For each 
address, an LD A,(HD is done to read the row. If the result 
is zero, the scan continues. If all addresses through 3840H 
are used and no key is found, the subroutine exits with 
zero in A. 

If a non-zero value is found, the row address is converted 
to 8 times the row number by successive adds of 8. The 
column number is then added to this by simply adding the 
value obtained from the read. We now have through 55. 

The shift key is read by a LD A,(3880H). If there's a shift, a 
value of 56 is added to the value from above. If there's no 
shift, is added. 

The index value is then used to pick up one byte from the 
KBLUT, the keyboard look up table. The last action is to 
delay 100 milliseconds by a timing loop. 

The KBLUT should be assembled with standard Radio 
Shack ASCII and control codes. Any other codes could be 
substituted by the user. The orientation of the codes is 
opposite that of Figure 7-1. The first 8 bytes, for example, 
would be the codes for @, A, B, C, D, E, F, and G. 
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Other Keyboard Subroutines 

We used some variations on the above routine in the 
programs of Chapters 13 and 14. Chapter 13 uses a special 
keyboard routine that is geared to a quick scan and return 
if no key has been pushed. The quick scan is implemented 
by an LD A,(387FH) shown in Figure 7-4. This reads in all of 
the rows at one time and merges all column bits. If there 
is a zero in A after this instruction, no key is being 
pressed. If the result is non-zero, the usual row-by-row 
scan is used. 



8429 F5 

842A 3A7F38 

842D B7 

842E CAB984 

8431 C5 

8432 E5 

8433 2AED85 
84 36 0161400 



06470 
064 80 
064 90 
06500 
06510 
06520 
06530 
06540 
06550 
06560 
06570 
06580 
06590 
06600 
06610 
06620 
06630 



<••••••• «»»»««»KEYBOARD INPUT SUB BOtl TINE" •»«•»««»«»»««• « 

« IF DEBOONCE DELAY LESS THAU ELAPSED TIME, SCANS » 

« KEYBOARD AND STORES POSSIBLE INPUT CHARACTER IN « 

» CIRCULAR INPUT BUFFER. * 

» ENTRY: NO PARAMETERS " 

» EXIT: NO PARAMETERS " 

« ALL REGISTERS SAVED * 

» CLEAR CHARACTER CAUSES RESTART AT M0R015H, SP RESET" 



PUSH 



| LD 



OR 

JP 

PUSH 

PUSH 

LD 

LD 



AF 



A,(387FH)| 



Z, I 

BC 

HL 

HL, 

BC, 



(TSLC) 
DBDEL 



SAVE REGISTERS 

ALL IN ONE SWELL FOOP 

TEST FOR ANY KEY 

GO IF NONE 



;GET TIME SINCE LAST CHARACTER 

; MINIMUM DELAY 
READS ALL 
KEYBOARD ROWS, 
MERGES ALL 
COLUMN BITS 



Figure 7-4. Quick Scan 



The INPUT subroutine of Chapter 14 (Figure 7-5 N i is a 
specialized keyboard input. It looks only for a through 8 
key by reading row 4 and row 5. Row 4 addresses keys 
through 7, while row 5 addresses only key 8 in bit 0. If a 
key is found, a 100 millisecond delay is done by calling the 
DELAY subroutine. 
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Input Subroutines 



Once you have implemented a keyboard input routine, it's 
fairly easy to write code to read in a string of characters. 
This is usually a subroutine that reads in the string but 
doesn't do syntax checking or make any judgments about 
the validity of the data that has been read in; that task is 
left to other routines that will process the input character 
string. 
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The "input string" subroutine must, however, make some 
checks. First, there must be some terminating input 
character that signifies the end of the input process. If 
there were not, the input-string subroutine would call the 
keyboard-input subroutine again for the next character, 
when the user was actually through with input. The 
terminating character in the TRS-80 is almost always 
ENTER. 

Second, there may be a maximum number of characters to 
be input. You may need to specify the number because the 
input buffer is of limited size, or because all input should 
be less than a certain number of characters. 

Other options for the input string routine might include a 
means to backspace (rubout) an incorrect character or 
characters from the string and a returned count of the 
number of characters input. 



Hints and Kinks 7-3 

Backspacing 

Backspacing is not implemented in the input 
routines of Chapters 14 and 15. The reason is 
that most input in routines of those chapters 
involves either one or two characters which 
are easily redone if an error is made. 

Also, implementation of backspacing is best 
done when the input involves an entire line of 
data, as it does in BASIC. When a line is 
input, an input buffer is filled with the 
character data before any processing is done. 
Processing is done after the terminating char- 
acter (ENTER in BASIC) has been entered. When 
the ' 'input line' ' approach is used, it is a 
simple matter to detect a backspace (left 
arrow or rubout), adjust the buffer pointer to 
point back at the last character, and then 
overwrite the last character. 

Have I given enough excuses? 
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Figure 7-6 shows a somewhat atypical input string sub- 
routine from the MORG program of Chapter 13. It calls a 
keyboard input routine called INPUTW that returns the 
next keyboard character. INPUTW specifically waits until a 
key has been pressed and always returns a character. The 
INPUTS subroutine terminates on an ENTER character, and 
each new character is compared to ENTER, which is 
EQU(ated) earlier in the program. (Note here that the code 
for ENTER in this keyboard program is 02H.) If the char- 
acter input is an ENTER, the subroutine is exited. Other- 
wise a character count is incremented in the C register, 
and the character is displayed on the screen by the DISCHR 
subroutine. 







06180 


»«»«»««»««»»»»«I N p(j T STRING SUBROUTINE»»*«»»»»««««»««»«» 






06190 


a 


INPUTS STRING OF CHARACTERS 


AT CURRENT COMMUNICA- » 






06200 


s 


TION AREA. 


TERMINATED BY ENTER. « 






06210 


9 


ENTRY; (B) 


rMAXIMUM NUMBER 


a 






06220 


fi 


(CURCUR)rCURRENT CURSOR POSITION « 






06230 


B 


EXIT: (B) 


=ACTUAL NUMBER INPUT » 






06240 


6 


(HL)=FIRST CHARACTER 


LOCATION » 






06250 


a 


NZ 


IF GT MAXIMUM NUMBER » 






06260 


a 


Z IF LE MAXIMUM NUMBER » 






06270 


a 


ALL REGISTERS SAVED EXCEPT 


-IL.BC.A « 






06280 










840D 


2AE985 


06290 


[NPUTS LD 


HL, (CURCUR) 


CURRENT CURSOR POSITION 


8410 


E5 


06300 




PUSH 


HL 


SAVE 


8111 


04 


06310 




INC 


B 


BUMP MAXIMUM 


8112 


0E00 


06320 




LD 


C.O 


INITIALIZE COUNT OF CHARS 


81114 


C5 


06330 


CNS010 POSH 


BC 


SAVE COUNTS 


8415 


CDF384 


06340 




CALL 


INPUTW 




GET CHARACTER 


84 18 


CI 


06350 




POP 


BC 




RESTORE COUNTS 


8419 


FE02 


06360 




CP 


ENTER 




TEST FOR DONE 


841B 


2809 


06370 




JR 


Z.INS030 




GO IF ENTER 


841D 


OC 


06 380 




INC 


C 




BUMP CHARACTER COUNT 


841E 


CDBE83 


06390 




CALL 


DISCHR 




DISPLAY 


8421 


10F1 


06400 




DJNZ 


INS0 10 




GO IF NOT MAXIMUM 


8423 


3EFF 


06410 




LD 


A.OFFH 


-1 TO A 


8425 


B7 


06420 




OR 


A 


RESET Z FLAG 


8426 


El 


06430 


[NS030 POP 


HL 


RETRIEVE START 


8427 


41 


06440 




LD 


B, C 


GET CHARACTER COUNT 


8428 


C9 


06450 




RET 




RETURN 






06460 













Figure 7-6. Input String 
Routine 
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Hints and Kinks 7-4 ■ 



Scanning Versus Waiting 

The usual keyboard input routine is a 

1 ' read-one-character-and-wait-until-input ' ' 

type. It will never return until that 

character has been input. The rationale is 

that this is the most frequent type of input; 

the program asks for user input before 

processing. 

The scanning type of input routine is used 
less frequently. Here, the program is 
processing merrily along but is keeping an eye 
out for a user stimulus. This stimulus is 
usually a user ''abort'' action, although it 
could be normal keyboard input, as in the case 
of the MORG program of Chapter 13. The goal in 
this type of input routine is to make certain 
that the polling of the keyboard input is done 
periodically at regular measured intervals (so 
that no characters are missed) and yet done 
fast enough that other processing can continue 
without being overburdened by the keyboard 
poll. 

In many other systems, input of infrequent 
(compared to CPU processing) keyboard 
characters would be accomplished by an 
interrupt from the keyboard when the next 
character was ready . That way, normal 
processing would continue until the keyboard 
interrupt was received, eliminating the 
polling task. One way to time the polling on a 
disk system is by using the system's 
real-time-clock. It provides 25 millisecond 
increments, which lend themselves nicely to 
timing any type of polling function. 



The B register initially held the maximum number of 
characters to be input plus one. After each character is 
input, B is decremented by a DJNZ. If less than the 
maximum has been input, the code goes to the next 
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character. If the maximum number of characters has been 
input, the subroutine is terminated with an error flag of 

"NZ". 

The characters are stored in the video display memory. 
This causes no problem as long as the characters are valid 
ASCII characters. However, non-standard characters may 
be changed in the upper-case versions of the TRS-80. The 
DISCHR routine is called to display the input characters 
because input in assembly language does not automati- 
cally display the characters as a BASIC input does! 

Display of Characters 

This brings us to a discussion of the next topic — what has 
to be done to display character data in assembly language? 
BASIC has built-in print driver routines that handle all 
output of characters. Character strings are "formatted" 
and tabbed, new lines are output, the screen "scrolls" 
automatically, etc. 

Unless you make calls to the BASIC routines to perform 
these functions, you must implement all display proces- 
sing via assembly-language routines. Fortunately, display 
processing is not that involved, and we'll look at some of 
the techniques here. 

Displaying A Message 

To display a message on the screen, a string of ASCII 
characters from a DEFM is output one at a time to the 
screen memory area. It's convenient to have a terminating 
character to end the message. The terminator we've used 
in the programs of Chapters 13 and 14 is a zero (null) at 
the end of each message. We used the zero because it is not 
a valid ASCII character and we can easily test it. 

An alternative to using zero is to use the disk Editor/ 
Assembler "DC" pseudo-op, which sets the high-order bit of 
the last character to one. This can also be easily detected 
(and masked out) for the "end of message." 



148 



Hints and Kinks 7-5 

DC Pseudo-Op 

Perhaps the DC pseudo-op should have been used 
in the code of Chapters 13 and 14 since it is 
specifically for generating character strings 
for output. The output routine would then test 
the sign bit of every character and terminate 
when a ' 'minus' ' was detected. The scheme used 
in the code of the applications programs 
wastes one byte for each message. Thank 
goodness memory is inexpensive! 



The screen area for the message is usually pointed to by 
the HL register or another register pair. It is incremented 
by one for every new ASCII byte output. Figure 7-7 shows 
the DSPMES subroutine from Chapter 13. This subroutine 
uses HL to point to the ASCII message and BC to address the 
"starting screen address." The starting screen address 
would be 3C00H through 3FFFH. 







011850 


c *« 


»»• 


••••••••DISPLAY MESSAGE 


AT LOCATION !)•••««««••»» 






01860 


• 


DISPLAYS MESSAGE AT 


GIVEN 


SCREEN POSITION. TER- 






01870 


9 


MINATES 


ON NULL (ZERO). 








04880 


C 


ENTRY: 


(HLJrMESSAGE 


LOCATION 






01890 


* 






(BC)=SCREEN 


'OSITION 






014 900 


• 


ALL REGISTERS SAVED 










04910 














36D 


F5 


01920 I 


JSPMES 


PUSH 


AF 




;SAVE REGISTERS 


36E 


C5 


01930 






PUSH 


BC 






36F 


E5 


01910 






PUSH 


HL 






370 


7E 


01950 I 


)SP005 


LD 


A, (HL) 




;GET MESSAGE CHAH 


371 


B7 


01960 






OR 


A 




jTEST FOR 


372 


2809 


01970 






JR 


Z.DSP010 




i RETURN IF DONE 


371 


02 


01980 






LD 


(BC) ,A 




;ST0RE CHARACTER 


375 


03 


01990 






INC 


BC 




;BUMP SCREEN POINTER 


376 


23 


05000 






INC 


HL 




;BUMP MESSAGE POINTER 


377 


ED13E985 


05010 






LD 


(CURCUR) 


BC 


;SAVE POINTER 


37B 


18F3 


05020 






JR 


DSP005 




;CONTINUE 


37D 


E1 


05030 I 


)SP010 


POP 


HL 




;REST0RE REGISTERS 


37E 


CI 


05010 






POP 


BC 






37F 


F1 


05050 






POP 


AF 






380 


C9 


05060 






RET 






:RETURN 



Figure 7-7. Display Message 
Routine 
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DSPMES also stores the "current cursor position" in vari- 
able CURCUR. This variable can be tested for "end of line" 
or "end of screen" (scrolling) conditions. 

Displaying an Input Character 

When you input a character from a keyboard routine, it 
must be immediately "echoed" to the screen by a "display 
character" routine. This subroutine would typically take a 
"current cursor position" and use it as the address of the 
screen position to store the input character. Figure 7-8 
shows such a routine that uses variable CURCUR as the 
current cursor position. 



33BE C5 

33BF E5 

33CO 2AE985 

B3C3 77 

B3CH 01FF3E 

B3C7 23 

83C8 22E985 

83CB B7 

83CC ED42 

83CE 2003 

33DO CDD683 

33D3 E1 

33DH C1 

83D5 C9 



05510 
05520 
05530 
05510 
05550 
05560 
05570 
05580 
05590 
05600 
05610 
05620 
05630 
056 40 
05650 
05660 
05670 
05680 
05690 
05700 
05710 
05720 
05730 



■•■••••••••DISPLAY CHARACTER SUB ROU TIKE »««««««««««»« » 

OUTPUTS ONE CHARACTER TO CURRENT CURSOR POSITION « 

ON SCREEN. MOVES CURSOR TO NEXT POSITION UNLESS • 

LAST CHARACTER POSITION OF LIKE 1 1 . IF LATTER, " 

SCROLLS UP FIRST. " 

ENTRY; ! CUR CUR )= CUR REN T CURSOR POSITION > 

(A)=CHARACTER TO BE OUTPUT " 

ALL REGISTERS SAVED. * 



PUSH 

PUSH 

LD 

LD 

LD 

INC 

LD 

OR 

SBC 

JR 

CALL 

POP 

POP 

RET 



BC 

HL 

HL, (CURCUR) 

( HL) , A 

BC.3CO0H+767 

HL 

(CURCUR ) , HL 

A 

HL.BC 

NZ.DIS010 

SCROLL 

HL 

BC 



;SAVE REGISTERS 

;GET CHARACTER POSITION 

iSTORE CHARACTER 

iLAST CP OF LINE 1 1 

;BUHP CURSOR 

;STORE 

;RESET CARRY 

:TEST FOR LAST 

; RETURN IF (10 SCROLL 

;SCROLL UP 

;RESTORE REGISTERS 

i RETURN 



Figure 7-8. Display Character 
Routine 



Scrolling 

DISCHR also tests CURCUR for a condition where scrolling 
is required. This condition normally occurs when the last 
character position on the screen, location 3FFFH, has been 
used. At that point you must scroll up the screen by 
moving lines 1 through 15 into lines through 14, and 
"blank" the last line. 

It's possible to scroll the first five or ten lines since we can 
format the screen any way we want — it's simply a matter 



150 



of coding! The SCROLL routine in Figure 7-9 scrolls the 
first 12 lines on the screen when the CURCUR reaches the 
end of the 12th line. Figure 7-10 shows the action. 
Scrolling on the TRS-80 is easy because of the LDIR 
block-move instruction and the fact that the screen is 
memory mapped. FILLCH is a "Fill Character" routine to 
fill the last line of the screen with blanks. 



LINE0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 







05740 
















05750 


■ »»» 


(••»«••«**) 


•SCROLL SCREEN 


SUBROUTIliE««««««««««««*»« 






05760 


> • 


SCROLLS LINES 1-11 UP TO 


LINES 0-10. FILLS LINE 1 1 






05770 


> * 


WITH BLANKS. 








05780 


, ft 


ENTRY; NO 


PARAMETERS 








05790 


. t 


ALL REGISTERS SAVED, 








05800 










83D6 


F5 


05810 


SCROLL PUSH 


AF 


;SAVE REGISTERS 


83D7 


C5 


05820 




PUSH 


BC 




83D8 


D5 


05830 




PUSH 


DE 




83D9 


E5 


05840 




PUSH 


HL 




83DA 


1 1003c 


05850 




LD 


DE, SCREEN 




START OF SCREEN 


83DD 


21403C 


05860 




LD 


HL.LINE1 




LINE I 


83E0 


010003 


05870 




LD 


BC, 1024-256 




II TO HOVE 


83E3 


EDB0 


05880 




JLDIR | 






MOVE EM 


83E5 


1 1C03E 


05890 




S LD 


DE, LINE1 1 




START OF LINE 1 1 


83E8 


3E20 


05900 




/ LD 


A , ' ' 




SPACE 


83EA 


014000 


05910 




/ LD 


BC.64 




II TO FILL 


83ED 


CD8385 


05920 




/ | CALL 


FILLCH | 




FILL LINE 


83F0 


21C03E 


05930 




/ LD 


HL, LINE\1 




START OF LINE 1 I 


83F3 


22E985 


05940 




LD 


(CURCUR A, HL 




RESET 


83F6 


E1 


05950 




POP 


HL \ 




RESTORE REGISTERS 


83F7 


D1 


05960 




POP 


DE \ 




83F8 


C1 


05970 




POP 


BC \ 




83F9 


F1 


05980 




POP 


AF \ 




83FA 


C9 


05990 




RET 


\ 


; RETURN 






" 


3LOCK 


' MOVE TO 


FILLS 12TH 






DO THE ACTUAL 


LINE WITH 






SCROLLING 


BLANKS AFTER 












SCROLL 





Figure 7-9. Scroll Screen 
Routine 




r ON SCROLLING 
LINES 1-11 
REPLACE 
LINE 0-10 



^THIS LINE 
FILLED WITH 
BLANKS 
AFTER SCROLL 



Figure 7-10. Scroll Action 
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Hints and Kinks 7-6 
Multiple Scrolling 



The TRS-80 screen can be divided up into any 
number of separate scroll areas by using the 
techniques shown in Figures 7-9 and 7-10. 
Implementing a ''split screen' ' capability, 
however, is another problem. Split screens 
split the screen into a right and left hand 
portion and can be very useful for comparing 
old text with new text or working with two 
' 'documents' ' at a time. 



TEXT ON LEFT 


TEXT ON RIGHT 




• 


. 


' 



One way to implement a split screen of this 
type would be to look for a screen address 
with the last 5 bits equal to 1 1111. This 
would denote the 31st character of either the 
left or right hand segments. This scheme works 
because lines start at ' '40H boundaries, ' ' as 
they are 64 characters wide; line addresses 
always start at XXOOH , XX40H, XX80H > or 
XXCOH. When this address was detected, the 
left or right hand pointer could be reset to 
the beginning of the line by adding 20H. 

Scrolling is also more tedious (read 
' 'messy' ' ) , because the areas involved are not 
contiguous . A scroll would have to be handled 
one 32-character line at a time. 

All of this is possible, but it might be best 
to orient your applications towards multiple 
screens stacked on top of each other, rather 
than side by side — unless you're the stubborn 
type .... 
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Conversion From ASCII Decimal to Binary 

A character string input from a keyboard or "input string" 
routine usually contains a mix of string data such as 
names and addresses and numeric data. The string data 
can be left as is in ASCII form for storage in arrays or 
records. However, you have to convert the numeric data to 
binary for processing. Any program that works with 
numeric data that is user entered invariably has a 
"decimal-to-binary" conversion routine. 

The algorithm for converting from ASCII characters of 
through 9 to binary goes something like this (and is shown 
in Figure 7-11): 

1. Clear a result total. 

2. Multiply the result total by 10. 

3. Get the leftmost ASCII character. 

4. Subtract 30H to get a binary value of through 9. 

5. Add the value to the result total. 

6. Repeat steps 2 through 5 for the next leftmost 
character until done. 







NUMBER IN BUFFER 
(ASCII) 








|1| 2| 3 |4 | 5 1 




STEP 


RESULT 


RESULT * 10 NEXT CHAR 


-30H 


l 

ADD TO RESULT 


1 
2 
3 

4 
5 




1 

12 
123 
1234 


31H 

10 32H 

120 33H 

1230 34H 

12340 35H 

Figure 7-11. Decimal-to- 
Action 


1 
2 
3 
4 
5 

■Binary 


1 

12 

123 

1234 

12345 

(BINARY) 



You can carry out this conversion process for a string of 
ASCII digits as long as need be. Practical sizes, however, 
are limited to values that can be held in 16 or 32 bits. 
Since 16 bits can hold up to 65535, a decimal-to-binary 
routine that works in 16 bits can process most applica- 
tions. 
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Decimal-to-binary routines also usually do testing of the 
ASCII characters to determine that they are valid ASCII 
values of 30H (0) through 39H (9). If they are found to be 
invalid values, the conversion is terminated with an 
"error" flag. 

Figure 7-12 shows a DECBIN subroutine from Chapter 13 
that converts a string of ASCII characters representing a 
decimal value to a binary value of through 65535. A 
"shift and add" technique is used to multiply by 10. The 
routine is entered with HL pointing to the buffer con- 
taining the string and B containing the number of char- 
acters to be converted. 



CLEAR RESULT TOTAL 



DE\CBIN POSH 
PUSH 
PUSH 




••••••••DECIMAL TO BINARY CONVERSION SUBROUTINE""" 1 

CONVERTS UP TO SIX ASCII CHARACTERS REPRESENTING 
DECIMAL NUMBER TO BINARY. MAXIMUM VALUE IS 65535. 
ENTRY: (HL)=BUFFER CONTAINING ASCII 

(B)=NUMBER OF CHARACTERS 
EXIT: (HL)=BINARY * 0-65535 

NZ IF INVALID ASCII CHARACTER OTHERWISE Z 
ALL REGISTERS SAVED EXCEPT A,HL 



MULTIPLY RESULT 
TOTAL BY 1B 



ADD 

PUSH 

ADD 

ADD 

POP 

ADD 



BC 



IX 



;SAVE REGISTERS 



IX, 



:SET RESULT 



IX, IX 
IX 

IX, IX 
IX, IX 
DE 
IX, DE 



i INTERMEDIATE'S 



A, (HL) 



30H 

M.DEC070 
10 
P.DEC070 



E. A 
D,0 



GET CHARACTER 



CONVERT 

GO IF LT "0" 

TEST FOR GT "9" 

GO IF GT "9" 



NOW IN E 
NOW IN DE 



MERGE 



HL 

DECOHO 

A.B 

IX 
HL 
IX 



GET BINARY 
VALUE 



;GO IF MORE 
;C0UNT TO A 
;SET OR RESET Z FLAG 
:HESULT TO HL 

RESTORE REGISTERS 



ADD TO 
RESULT 
TOTAL 



Figure 7-12. Decimal-to-Binary 
Routine 
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The conversion loop is executed "B" times. After the sub- 
tract of 30H, an error return is made if the result is 
negative (less than 30H), or greater than 9 (greater than 
39H). An NZ condition is present on return if there was an 
invalid character. 

Converting From Binary to Decimal ASCII 

This processing converts binary data back into displayable 
or printable form. As in the case of DECBIN above, the 
same size limitations apply. Usually 16 or 32 bits of binary 
data are converted to ASCII decimal digits. 



The 
ing: 



'normal" algorithm for this conversion is the follow- 



1. Divide the binary data by 10. 

2. Save the quotient of the divide for the next divide. 

3. Add 30H to the remainder to produce an ASCII 
through 9. 

4. Store the ASCII character at the next rightmost 
character position in a buffer. 

5. Repeat steps 1 through 4 until the quotient is zero. 
These steps are shown in Figure 7-13. 





DIVIDE BY 10 

12345/10 

1234/10 

123/10 

12/10 

1/10 


NUME 

Q 
1234 
123 

12 

1 




1ER IN REG 
(BINARY) 


ISTER 

,DD30HTOR 

35H 
34H 
33H 
32H 
31 H 




STEP 


112,3451 

R A 

5 
4 
3 
2 
1 


! STORE IN BUFFER 


1 
2 


I I I I ISiCASC 

I I I Ul5l 


3 


I I I3l4l5l 


4 
5 


I |2|3|4|5| 
|1|2|3|4|5| 



Figure 7-13. Binary-to-Decimal 
Action 
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The BINDEC subroutine of Figure 7-14, however, employs 
an alternative approach. It uses a "divide by powers of 10" 
method of conversion. Starting with 10000, it performs 
successive subtractions on the binary number to divide by 
the power of 10. The quotient for each subtract is the 
power of 10 digit, which is then converted to ASCII. Suc- 
cessively smaller powers of 10 down to 1 are used. The 
algorithm for this is shown in Figure 7-15. 



eoGo 


00100 






ORG 


8000H 














001 10 


SS 


*«**«**«» **««s*e«»*«i!ff»**sa«fi**s*fi«fnf***fi»fi*e9fi»*3*»in» 






00120 


s 






BINARY TO 


DECIMAL SR 


» 






01-30 


c 


ENTRY: ( HL) = 


16-BIT BINARY VALUE 


e 






00140 


s 




(IX) = 


POINTER TO 


START 


OF CHARACTER BUFFER 


9 






00150 


* 


EXIT; (BUFFER)=FILLL'B 


WITH 


FIVE ASCII CHARACTERS, 


a 






00160 


« 




LEADING ZEROES 




s 






00170 


* 




( IX) 


=BUFFER+5 






B 






00180 


gs 


B»fi***«B*»fi*B9ft»e»6«B***»«»»#fi»«**J(*»a»««»»9««*«5««B«S 






00190 
















6000 


FD212580 00200 


3IHDEC 


LD 


IY, PTABLE 




; POWER OF 10 TABLE 




8004 


AF 


0021 


3IN010 


XOR 


A 




; DIGIT COUNT TO 




8005 


FD5601 


00220 






LD 


D, ( IY + 1 ) 




;GET MS BYTE 




8008 


FD5E00 


00230 






LD 


E,(IY+0) 




;GET LS BYTE 




800B 


E7 


00240 


3IN020 


OR 


A 






CLEAR CARRY 




800C 


ED52 


00250 






SBC 


HL.DE 






SUBTRACT POWER OF 


10 


800E 


3803 


00260 






JR 


C.BIN030 






GO IF NEGATIVE 




8010 


3C 


270 






INC 


A 






BUMP DIGIT COUNT 




8011 


18F8 


00280 






JR 


BIH020 






CONTINUE 




8013 


19 


00290 


3IN03 


ADD 


HL.DE 




;RESTORE TO POSITIVE 




80111 


C630 


00300 






ADD 


A.30H 




;COHVEHT TO ASCII 




8016 


DD7700 


00310 






LD 


( IX-t-0 1 , A 




;ST0RE IN BUFFER 




8019 


DD23 


00320 






INC 


IX 




;BUMP BUF POINTER 




801B 


FD23 


00330 






INC 


IY 




J BUMP PWR 10 PNTR 




801D 


FD23 


00335 






INC 


IY 








801F 


7B 


00340 






LD 


A, E 




;GET LS BYTE 




8020 


FE01 


00350 






CP 


1 




jTEST FOR 5 DIGITS 




8022 


20E0 


00360 






JR 


NZ.BIN010 




JGO IF NOT 5 




8021) 


C9 


00370 






RET 






; RETURN 




8025 


1027 


00380 


'TABLE 


DEFW 


10000 








8027 


E803 


00390 






DEFW 


1000 








8029 


6400 


00400 






DEFW 


100 








802B 


0A00 


004 10 






DEFW 


10 








802D 


0100 


00420 






DEFH 


1 








0000 




004 30 






END 










00000 TOTAL 


ERRORS 



















Figure 7-14. Binary-to-Decimal 
Routine 
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NUMBER: 12345 
-10000 



POWER OF 10 



2345 
-10000 

-xxxxx 

+10000 

2345 
-1000 

1345 
-1000 

345 
-1000 

-XXXX 

+1000 

345 
-100 

245 
-100 

145 
-100 

45 
-100 

-XXX 

+100 

45 
-10 



35 
-10 

25 
-10 

15 
-10 

5 
-10 

-X 

+10 

5 
-1 

4 
-1 

3 
-1 



2 

-1 


1 
-1 



-1 


-X 

+ 1 



10000 1000 



once 



100 



10 



twice 



twice 



three 



twice 



three 



four 



twice 



three 



four 



five 



Figure7-15. "Powers of Ten" 
Binary to Decimal 
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This subroutine converts a 16-bit binary number into 5 
ASCII digits and returns a pointer to the last digit plus one. 
There are no error conditions for conversion of the 16-bit 
value. 



■Hints and Kinks 7-7 



Converting Between ASCII and Binary or Hex 

Converting from an ASCII string of characters 
representing binary or hexadecimal digits or 
the other way around isn't done as frequently 
as decimal/ASCII conversion. However, each 
conversion is relatively easy, since no 
multiplication must be done; the process 
simply involves stripping off one or four bits 
and translating them one at a time to ASCII, 
or vice versa. 

To convert from ASCII to binary, get the ASCII 
character and subtract 30H, You now have a 
binary one or zero. Shift to the next bit 
position and repeat the process for the number 
of characters in the string. 

To convert from binary to ASCII, get the next 
bit and add 30H. You now have an ASCII or 1 , 
Store in the output buffer and go on to the 
next bit . 

To convert from ASCII to hexadecimal, do this: 
Get the next ASCII character. This will be 
30H-39H, or 41H( A)-46H(F) . Subtract 30H. If 
the result is greater than 9, subtract 7 (this 
adjusts for the ASCII characters between 9 and 
0) . You now have a hex through F. Store in 
the next 4 bits and repeat the process for the 
next ASCII character. 

To convert from hexadecimal to ASCII; Get the 
next group of four bits. Add 30H. If the 
result is greater than 39H, add 7. You now 
have an ASCII through 9, A, B, C, D, EorF. 
Store in the buffer, and go on to the next 
group of four bits. 
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Chapter Eight 
Working With Tables 

Tables are some of the most common data structures 
used in assembly-language programming. Tables are so 
common that large programs that use many tables to 
define program operations are said to be table driven as 
opposed to more "processing-oriented." We'll discuss types 
of tables followed by some searching and sorting 
operations that can be performed in assembly language. 



What are Tables? 

A loose definition of a table is any collection of data items 
arranged in one contiguous block of memory. The data 
items may be ordered by some key value or unordered. 
Each entry in a table may consist of one or more bytes. 
The entry may contain a number of fields that are associ- 
ated with the entry, or there may only be one field or item. 
The entry itself may be fixed length or variable length, 
and the table may also be either fixed or variable length. ' 



Fixed Length Entry/Fixed Length Table 

Let's take a look at a typical simple table. The MOVETB 
from Chapter 15 is a five-entry fixed-length table; it's 
shown in Figure 8-1. Each entry is two bytes long, making 
the total table length 10 bytes. Each entry of the MOVETB 
is an address defining the location of a "space cell" in a 
tic-tac-toe game (see Chapter 15). 
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MOVETB + © 

+ 1 " 


ADDRESS FOR 

" MOVE 1 


+ 2 
+ 3 


ADDRESS FOR 
" MOVE 2 


+ 4 
+ 5 


ADDRESS FOR 
■ MOVE 3 


+ 6 _ 

+ 7 


ADDRESS FOR 
* MOVE 4 


+ 8 _ 

+ 9 


ALWAYS 

© 



Figure 8-1. FiKed-Length Entry/ 
FiKed-Length Table 



The entries in MOVETB are indexed by the move number 
of the tic-tac-toe game. The (computer) moves are 
numbered 1 through 4, so to get the address associated 
with any move, the formula is 

MOVETB ENTRY ADDRESS = 
MOVETB + 2* (MOVE # -1 > 

Typical code for accessing the table is shown in Figure 8-2 
from the MAIN3 subroutine of Chapter 15. Here, A is loaded 
with the move number, MOVENO. This is decremented by 
one to find the previous move number and then multiplied 
by two. This index value is then loaded into the BC 
register pair. IX is then loaded with the address of the 
table start MOVETB, and BC is added to IX. IX now points to 
the MOVETB entry for the previous move. The address in 
the entry is picked up in HL by two LD instructions that 
use the index register. 
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Here we didn't order the data in the table (namely, the 
five entries were not arranged in numerical sequence) but 
related them to an external index and accessed them by 
that index value. 
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Fixed Length Entry/ 
Variable Length Table 

Another table that illustrates what we mean by "table 
driven" is shown in Figure 8-3. The GRIDTB of the figure is 
used in Chapter 15 to define a tic-tac-toe grid. There are 
16 entries in the table, each one defining a line segment to 
be drawn by the DRAWL subroutine of that chapter. Each 
entry consists of five bytes and there are four fields within 
each entry. 



GRIDTB + 




+ 5 
+ 10 
+ 15 






+ 20 




+ 25 




+ 30 




+ 35 




+ 40 




+ 45 
+ 50 
+ 55 
+ 60 








+ 65 




+ 70 




+ 75 




+ 80 


-1 



, 16 ENTRIES OF 
5 BYTES EACH 



TERMINATOR = —1 



Figure 8-3. Fixed-Length Entry/ 
Variable-Length Table 



The first, second, and third fields of the entry are each one 
byte long, and the fourth field is two bytes long as shown 
in Figure 8-4. (The first field defines the graphics charac- 
ter to be stored; the second is for a horizontal line or 1 for 
a vertical line; the third represents the number of charac- 
ter positions in the line; and the fourth field is the starting 
screen address for the line.) 
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+0 
+1 

+ 2 
+ 3 
+ 4 



GRAPHICS CHARACTER 



= HORIZ 1=VERT 



#CHARACTER POS'NS 



STARTING 
SCREEN ADDRESS 



Figure 8-4. Entry Fields in GRIDTB 



The last byte of the table is a terminator of -1. The termi- 
nator marks the end of the table and may be any value 
that is not a legitimate value for an entry in the table. 
You use the table by setting a pointer to the beginning 
and picking up the five bytes of each entry. After you have 
drawn the line, you increment the pointer by 5 and the 
code loops back to pick up the next entry. This continues 
until the -1 terminator is found. The code for accessing 
this table is shown in Figure 8-5. 









00350 


S DRAW 


GRID 


HERE 




oom ' 


DD 


21 0000« 


00360 




LD 


IX, GRIDTB 


;TABLE FOR GRID 


0018 ' 


DD 


TE 00 


00370 


ART005 


LD 


A, (IX) 


;GET CHARACTER 


001 B' 


FE 


FF 


00380 




CP 


OFFH 


;TEST FOR TERMINATOR 


001 D' 


28 


16 


00390 




JR 


Z.ART008 


;GO IF DONE 


001F' 


DD 


4E 01 


00400 




LD 


C. i IX+1 ) 


;LOAD HORIZ/VERT 


0022 ' 


DD 


46 02 


001) 10 




LD 


B, (IX+23 


;L0AD I OF CHAR POSNS 


0025 ' 


DD 


6E 03 


00420 




LD 


L.UX+3) 


iSTART OF LINE, LSB 


0028 ' 


DD 


6 6 01 


00430 




LD 


H,(IX+4 ) 


;START OF LINE, MSB 


002B' 


CD 


0000« 


oornio 




CALL 


DHAWL 


;DRAW LINE 


002E' 


01 


0005 


001150 




LD 


BC,5 


;5 BYTES PER LINE 


0031 ' 


DD 


09 


00460 




ADD 


IX, BC 


; POINT TO NEXT LINE 


0033' 


18 


E3 


00470 




JR 


ART005 


;GO FOR NEXT LINE 



Figure 8-5. Table Use With Terminator 



This somewhat "sloppy" table groups similar data together 
and helps "modularize" code. We could have incorporated 
all of the code to draw the grid into in-line code, but it's a 
lot neater and efficient to put it into a table such as 
GRIDTB. 
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Variable Length Entry/ 
Variable Length Table 

The tables above had fixed-length entries. In the case of 
MOVETB, the number of entries was fixed at five. GR1DTB 
had a variable number of entries, the end of the table 
being denoted by a terminator of -1. 

An example of a table consisting of variable-length 
entries with a variable number of entries is shown in 
Figure 8-6. The PTABLE, or Permutation Table, is used in 
Chapter 15 to hold configurations of tic-tac-toe games. 



PTABLE 



VARYINQ 

LENGTHS 




ENTRY 



ENTRY N 



/TYPICAL* 
I ENTRY I 



- CONFIGURATION - 


# OF SPACES 


1ST SPACE 


2ND SPACE 


3RD SPACE 


4TH SPACE 


5TH SPACE 


6TH SPACE 


7TH SPACE 



Figure 8-6. Variable-Length Entry/ 
Variable-Length Table 
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The configuration for each tic-tac-toe game is held in the 
first two bytes of each entry in a special binary-coded 
form. The next byte defines the number of "spaces" in the 
tic-tac-toe configuration, from 3 to 9. The next 3 to 9 bytes 
represent a count related to each space. The length of each 
entry is therefore 2 + l + N where N is 3 to 9 or 6 to 12 bytes. 
When a search is made of the PTABLE, the length of the 
current entry must be computed by adding 3 plus the 
number found in the third byte. 

PTABLE also has a variable number of entries, as the num- 
ber of possible tic-tac-toe permutations is calculated 
dynamically (during program execution) by the 
tic-tac-toe program. In this case there is no terminator 
since a search of the PTABLE for a specific configuration 
must be successful. You don't have to have a terminator 
because the program will have a severe logic error if an 
entry is not found. The only action an unsuccessful search 
might produce would be a print-out message: FINISH 
DEBUGGING THE PROGRAM!! 



Jump Tables 

Another common type of table is a "jump table" or "branch 
table." This type of table is shown in Figure 8-7 in code 
from the MORG program of Chapter 14. It is used in similar 
fashion to a BASIC "computed GOTO" (ON N GOTO 100, 200, 
300. . .). Its entries define the addresses of processing 
routines for the program where there are many different 
types of processing to be performed. 
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01130 






01140 






01150 


80BE 


CI 


01160 


80BF 


D3 


01170 


80C0 


D2 


01180 


80C1 


BO 


01 190 


80C2 


B1 


01200 


80C3 


B2 


01210 


80 CI 


B3 


01220 


80C5 


B1 


01230 


80C6 


B5 


01210 


80C7 


B6 


01250 


80C8 


B7 


01260 


80C9 


B8 


01270 


80CA 


B9 


01280 


80CB 


DO 


01290 


80CC 


CE 


01300 


OOOF 




01310 
01320 
01330 
01310 


80CD 


EB80 


01350 


80CF 


91 81 


01360 


80D1 


F081 


01370 


80D3 


3782 


01380 


80D5 


3782 


01390 


80D7 


3782 


01100 


80D9 


3782 


01110 


80DB 


3782 


01120 


80DD 


3782 


01130 


80DF 


3782 


01110 


80E1 


3782 


01150 


80E3 


3782 


01160 


80E5 


3782 


01170 


80 E7 


8B82 


01180 


80E9 


B182 


01190 



; FUNCTION TABLE 






FTAB DEFB 


■D 


+ 80H 


DEFB 


'S 


+ 80H 


DEFB 


'R 


+ 80H 


DEFB 


'0 


+ 80H 


DEFB 


1 1 


+ 80H 


DEFB 


'2 


+ 80H 


DEFB 


'3 


+ 80H 


DEFB 


'1 


+ 80H 


DEFB 


'5 


+ 80H 


DEFB 


'6 


+ 80H 


DEFB 


'7 


*80H 


DEFB 


'8 


+ 80H 


DEFB 


'9 


+ 80H 


DEFB 


' P 


+ 80H 


DEFB 


•N'+80H 



$-FTAB 



BRANCH TABLE 



BTAB 


DEFW 


DEFINE 




DEFW 


SPEED 




DEFW 


RANDOM 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


XMIT 




DEFW 


PRINT 




DEFW 


NOPRNT 



15 ONE-BYTE ENTRIES 
IN (TAB 



DEFINE MESSAGE 
DEFINE SPEED 
TRANSMIT RANDOM 
TRANSMIT MESSAGE 
1 
2 

3 
1 
5 
6 
7 



SET PRJNT 

RESET PRINT 

SIZE OF FUNCTION TABLE 



DEFINE MESSAGE 
DEFINE SPEED 
TRANSMIT RANDOM 
TRANSMIT MESSAGE 
1 
2 
3 
1 

5 
6 
7 



SET PRINT 
RESET PRINT 



15 TWO-BYTE ENTRIES 
IN BTAB. POSITION OF 
' EACH CORRESPONDS TO 
FTAB ENTRY 



Figure 8-7. Jump Table 

The index of the processing routine is determined by find- 
ing an entry in another table, which typically holds a set 
of one-character function codes. 

In the code, FTAB holds all of the possible input characters 
that define special functions in the MORG program. The 
80H represents a SHIFT. When the user inputs a SHIFT D, 
for example, processing of the Define Message must take 
place; when a SHIFT 8 is input, message 8 must be trans- 
mitted. 
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The FTAB is first scanned for the input code character. If 
it's found, the index to FTAB is then used to get the branch 
address from the BTAB. The code for the scan is shown in 
Figure 8-8. 



807D BO 

807E 21CC80 

8081 060F 

8083 BE 

8084 2825 

8086 2B 

8087 10FA 
8089 E67F 



808B 
808E 
8090 
8093 
8096 
8097 
8099 
809C 
809F 
80A2 
80A5 
80A6 
80A9 
80AB 
80AC 
80 AD 
80AF 
80B1 
80B5 
80B7 
80BA 
80BD 



32DC85 

3EFF 

32DD85 

21DC85 

7E 

FE20 

FA6480 

CDBE83 

CD81 83 

CDE082 

23 

CD2984 

18EB 

18 

OD 

0600 

CB21 

DB21CD80 

DD09 

DD660 1 

DD6E00 

E9 



00820 
00830 
00840 
00850 
00860 
00870 
00880 
00890 
00900 
00910 
00920 
00930 
00940 
00950 
00960 
00970 
00980 
00990 
01000 
01010 
01020 
01030 
01040 
01050 
01060 
01070 
01080 
01090 
01 100 
01110 
01120 



SETUP AND SCAN 
FTAB FOR INPUT CODE 
CHARACTER 



K0R022' 1 OB 



LD 

LD 

CP 

JR 

DEC 

DJNZ 



HL.FTAB+FTABS-1 

B, FTABS 

<HL) 

Z.M0R030 

HL 

M0B025 



MERGE SHIFT BIT 



FUNCTION TABLE END ADD 
FUNCTION TABLE SIZE 

TEST FOR FUNCTION 

GO IF FOUND 

POINT TO NEXT FUNCTION 

CONTINUE 



AND 



7FH 



NOT FUNCTION HERE - TRANSMIT A 



LD 

LD 

LD 

LD 

LD 

CP 

JP 

CALL 

CALL 

CALL 

INC 

CALL 

JR 



(TMP1 ) ,A 
A.OFFH 
(TMP1+1 ) , 
HL.TMP1 
A. (HL) 

M.MOR020 

DISCHR 

LPRINT 

SNDCHR 

HL 

INPUT 

MOR0 27 



;RESET BI 
SINGLE C 

; STORE IN 

;-1 

;ST0RE TE 

: ADDRESS 

GET NE 

TEST F 

GO IF 

DISPLA 

PRINT 

SEND 

POINT 

TEST F 

;CONTIN 



T 7 

HARACTER 
TEMP BUFFER 

RUINATOR 

OF "MESSAGE" 

XT CHARACTER 

OR NON-ASCII 

END OF MESSAGE 

X CHARACTER 

IF REQUIRED 

HARACTER 

TO NEXT 

OR INPUT 

UE SENDING 



MOR030 


LD 


C,B 


INDEX+1 NOW IN C 




DEC 


C 


ADJUST FOR INDEX 




LD 


B, 


INDEX NOW IN BC 




SLA 


C 


2«INDEX NOW IN BC 




LD 


IX, BTAB 


BRANCH TABLE 




ADD 


IX, BC 


POINT TO BRANCH 




LD 


H,(IX+1 ) 


GET MSB OF ADDRESS 




LD 


L,(IX) 


GET LSB OF ADDRESS 




JP 


(HL) 


BRANCH OUT 



T 



CONVERT FTAB INDEX 
TO BTAB INDEX, GET 
ADDRESS AND BRANCH 
OUT 



Figure 8-8. Jump Table Use 

At MOR025 , A holds the input character, and B holds the 
FTAB size, FTABS. FTABS is automatically computed at 
assembly time. The HL register holds a pointer to the end 
of the FTAB, set up by loading HL with FTAB + FTABS-l. 
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- Hints and Kinks 8-1 - 
Automatic Table Size 



Programmers commonly use an expression like 
FTABS EQU $-FTAB to have the assembler 
calculate table size, Entries can then be 
added in the table without having to change 
program constants. FTABS will be stored in the 
assembler symbol table with a value equal to 
the number of bytes in the table. As symbol 
table entries are 16 bits, this method works 
even for very long tables. 



A CP is done to search the table. If the entry in FTAB does 
not compare, HL is decremented to point to the next lower 
entry. A DJNZ is then done back to MOR025. If the contents 
of B have been decremented down to zero, all entries have 
been compared and the search is unsuccessful. If the entry 
is found, the instruction at location MOR030 is executed. 

At MOR030, the B register contains an index value to the 
FTAB character of through 15 (FTABS). This index is 
transferred to BC, and then multiplied by two (SLA C). The 
IX register is now loaded with the start of BTAB, and BC is 
added to IX to point to the entry in BTAB corresponding to 
the FTAB entry. Note at this point, that IX only points to 
the BTAB entry; we have not picked up any address. 

The next two instructions load H with the most significant 
byte of the entry and load L with the least significant byte 
of the entry. HL now contains the address of the processing 
routine from BTAB and a JP (HL) causes a jump out to the 
processing routine. 

Using a branch table in this fashion is much cleaner than 
doing the equivalent in-line code of — 

CP 'D'+80H iTEST FOR DEFINE 
JP ZtDEFINE 5G0 IF DEFINE 
CP 'S'+BOH 5TEST FOR SPEED 
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JP ZtSPEED ;go if speed 



Hints and Kinks 8-2' 



When to Use Branch Tables 

Admittedly, there's a lot of ''overhead'' in 
branch table processing, One major difficulty- 
is picking up a branch address. It would be 
nice to be able to use indexed addressing to 
pick up a 16-bit value instead of picking up 
the value one byte at a time. 

Let's analyze the approach here. One way to 
branch out would have been 

CP 'D'+80H IIS THIS DEFINE MESSAGE 

JP Z. DEFINE 5G0 IF YES 

CP 'S'+80H 5IS THIS DEFINE SPEED 

JP Z »SPEED iGO IF YES 

This approach is clean and simple to debug. 
You would have used five bytes for each 
branch. The code shown in Figure 8-8 uses 
about 75 bytes, counting table storage. In 
this one example, then, 15 branch points would 
have been the ' 'break even' ' point in terms of 
memory storage. Of course, there's also the 
factors of difficulty of coding and debugging, 
but it seems reasonable to use branch tables 
for anything over 20 or so entries. (Or 15 or 
so if you're writing a book on assembly 
language. ) . 



Scanning 

In the code above, we searched or scanned the FTAB for the 
key value. In this particular case, we scanned 
backwards. The usual procedure is to scan forwards 
through the table. The code of Figure 8-9 is a "Find 
Message" subroutine that searches a table of messages for 
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a given message number. The format of the Message Table 
MTAB is shown in Figure 8-10. It consists of ASCII 
characters, message numbers of through 9, or -1 
terminator values. 



82C7 
82C8 



C5 
CDDT82 



82CB 2807 
82CD F5 
82CE 3EFF 
82D0 CDD782 
82D3 F1 
82D1I CI 
82D5 2B 
82D6 C9 
82D7 21EA88 
82DA 010B0A 
82DD EDB1 
82DF C9 



03680 
03690 
03700 
03710 
03720 
03730 
03740 
03750 
03760 
03770 
03780 
03790 
03800 
03810 
03820 
03830 
03840 
03850 
03860 
03870 
03880 
03890 
03900 
03910 



s89»»s«B«BaBfi»fi8 89»FNDMSG SUB R0U TINE* «**«*»»«»»•»*» 

« FINDS MESSAGE BI SCANNING MBUF FOR 0-9- 0-9 IS 

• MESSAGE i. ASCII CHARACTERS ARE CHARACTERS TO 

• BE SENT. -1 IS PADDING AT END OF MESSAGE. 
» ENTRI: (Ai=MESSAGE t 

• EXIT: (HL)=P0INTER TO MESSAGE IF Z OH 

« POINTER TO NEXT AVAILABLE IF NZ 

« RESET 

• ALL REGISTERS SAVED EXCEPT HL 



FNDHSG 


PUSH 


BC 


;SAVE BC 




CALL 


FNDSR 


;SEARCH 




JR 


Z.FND020 


;G0 IF FOUND 




iPUSH 


AF 


;SAVE NOT FND FLAG 




LD 


A.OFFH 


;F0R FIRST AVAILABLE 




CALL 


FNDSR 


;SEARCH 


i 


POP 


AF A ;GET FLAG 


FND020/ 


POP 


BC 


;REST0RE BC 




DEC 


HL 


;ADJUST HL 


/ 


RET 




;RETURN 


FNDSR/ 


LD 


HL.MBUF 


;START OF MSG BUFFER 


/ 


LD 


BC2571 


;SIZE OF MBUF 


/ 


CPIR 




;COMPARE 


/ 


RET 




; RETURN 



LOOK FOR 

GIVEN MESSAGE # 



GIVEN MESSAGE # 
NOT FOUND, LOOK 
FOR NEXT AVAILABLE 



Figure 8-9. Scanning Example 



MTAB +0 

+ 1 
+ 2 
+ 3 



+ 2569 
+ 2570 



M 











MESSAGE #5 
"MESSAGE" 



> MESSAGE #8 
"TRS-8a" 



} 



TERMINATOR 



Figure 8-10. MTAB Format 
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You do the scan by a "block compare" instruction that 
compares the contents of A (the message #) with each byte 
of the table starting with MBUF and continuing through 
2571 bytes. If the entry in MBUF compares, the Z flag is 
set, and HL points to the entry plus one. 



Hints and Kinks 8-3 

Block Compares 

The setup for a block compare looks like this: 

(HL) = Start of data for compare 

(BC) = Number of bytes in comparison area 

(A) = Search value 

You then execute a CPIR instruction. It'll go 
through the block of memory for the number of 
bytes specified in BC and compare each memory 
byte with the search value. If a match is 
found, CPIR will stop with the Z flag set, and 
HL pointing one byte past the matching value . 
(The reason for this is that the increment of 
HL is done before the comparison, ) If the 
search value is not found in the memory block, 
the Z flag will not be set after the CPIR, and 
HL will point to the last byte plus one. 

The CPDR performs much the same action but 
searches the block backwards. The CPI and CPD 
perform one comparison at a time, requiring a 
loop to be made back to the CPI or CPD. 



The first part of the code looks for the given message 
number. If it isn't found (NZ), another CALL is made to 
FNDSR to search for the first -1 terminator. On exit, HL 
points to the message number if found or the first -1 byte. 
The Z flag is set if the message number was found. 

The block compare instructions may be used conveniently 
to search a table of one-byte entries forwards or backwards 
(CPDR). They're very fast in comparison to other code 
sequences. 
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Ordered Tables 

All of the above examples involved tables of unordered 
data. Scanning forwards or backwards through the table 
located one entry, an item at a time, until a match was 
found, or until the end (or beginning) of the table was 
reached. In the following discussion, we'll be concerned 
with operations on ordered tables. 



■Hints and Kinks 8-4- 
Ordered Tables 



Tables are usually ordered in ascending order 
based on numeric ' 'weight. ' ' One-byte 
entries pose no problem. Two-byte entry tables 
for numeric values will probably be in 
standard Z-80 16-bit address format, least 
significant byte followed by most significant 
byte. Greater than two-byte entries are not 
often found for numeric tables, but are common 
for strings . 

ASCII strings in tables are also usually 
ordered on the basis of numeric weight. This 
means that you will use the hex equivalent of 
the ASCII value in determining whether one 
value is smaller than the next. This puts 
upper-case characters before lower case 
(TRS-80 before tRS-80, for example and 
BIV.ROY G. after BIV ROY G) . 



The techniques for ordered tables (data entries are in 
ascending or descending order) are geared towards fast 
searches to find specific data items and sorts to organize 
the data in orderly fashion. 
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Searching 

Suppose that we have a table of ordered data. We'll 
assume the table is made up of fixed-length entries, and 
it's a fixed number of entries. How do we search the 
entries in the table? 



Sequential Search 

The first way, of course, would be to scan the table 
sequentially as we have been doing. Even though assem- 
bly language is fast, the search time for a sequential 
search may become quite significant when large amounts 
of data are to be processed. We might be using the 
sequential search for a sort, for example. The entries in a 
table would be consecutively searched for the next 
smallest item and put into a second, sorted table. If there 
were 1000 entries, we'd have to search all 1000 to find the 
next smallest item, and we'd have to do that for 1000 
items. This would mean 1000*1000 iterations, or about 
1,000,000 iterations. If each iteration took 70 microseconds 
(about 12 instruction times), the total sort time would be 
70 microseconds * 1,000,000, or 70 seconds! Although this 
is the blink of an eye compared to the equivalent BASIC 
code, there is an occasional need for fast searches of 
ordered data. One of the "standard" high-speed search 
methods is the binary search. 



Binary Search 

In this search, the midpoint of the entries is compared to 
the search key. If the entry is greater than the search 
key, the top half of the table is discarded and the next 
comparison is made in the midpoint of the bottom half; if 
the entry is less than the sort key, the bottom half of the 
table is discarded and the next comparison is made in the 
midpoint of the top half. This division by 2 continues for 
smaller and smaller segments of the table until the entry 
is found or until the last segment (one entry!) has been 
compared and no match has been made (see Figure 8-11). 
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15 


SEARCH KEY 




SORTED 






TABLE 










TRY 1 TRY 2 


TRY3 


TRY 4 




1 










1 










2 










3 










4 










5 










6 










7 










8 


8<15 








10 


UJ 










11 


Z 
< 










12 


K 


12<15 










(0 


UJ 










13 


X 


(3 










14 


Z 


z 
< 




14<15 






15 


EC 




UJ 




15 = 15 




s 


</> 




cr 






1 16 


UJ 


I 




UJ 










H 






K 




X 







Figure 8-11. Binary Search Algorithm 

Figure 8-12 shows this binary search technique imple- 
mented in an assembly-language program. BINSRC is 
designed to search a table made up of 16-bit entries for a 
given search value. The entries are ordered in ascending 
fashion and are in standard Z-80 16-bit format, least sig- 
nificant byte followed by most significant byte. 



000 




00100 
001 10 
00120 
00130 
001H0 
00150 
00160 
00170 
001 80 


000 


F5 


00190 


001 


D5 


00200 


002 


DDE5 


00210 


oot 


226680 


00220 


07 


ED535E80 


00230 


00B 


1 10000 


00210 



ftillllil 



BRBOsaa 



G 8000H 

INARY SEARCH OF 16-BIT ENTRY TABLE 

(DE)=* OF ENTRIES 

(BC)=SEARCH VALUE 

(HL)=START OF TABLE 

(HL)rENTRY LOCATION OR -1 IF NOT FOUND 

ALL OTHER REGISTERS SAVE 



sa«fi*Bfifi«»9«»*»8*»*a*»fl 



800E ED536080 00250 



PUSH 


AF 


PUSH 


DE 


PUSH 


IX 


LD 


( START) 


LD 


(HI) ,DE 


LD 


DE,0 


LD 


(LO) , DE 



;SAVE REGISTERS 



SAVE TABLE START 

HIGH VALUE 

ZERO 

LOU VALUE 
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8012 
8016 
8019 
801 A 
801C 
801E 
8020 
8023 
8024 
8027 
8028 
802C 
802D 
802E 
8030 
8033 
8036 
8037 
8039 
803C 
803E 
8010 
80113 
8046 
8047 
8048 
804 A 
804C 
804 F 
8051 
8053 
8054 
8056 
8057 
8058 
8059 
805C 
0002 
0002 
0002 
0002 
0002 
0000 
0000 



ED5B6080 

2A5E80 

B7 

ED52 

CB3C 

CB1D 

226480 

19 

226 280 

29 

ED5B668C 

19 

E5 

DDE1 

DD660 1 

DD6E00 

B7 

ED42 

2A6280 

2813 

300C 

226080 

2A6480 

7C 

B5 

280F 

18C6 

225E80 

18F2 

DDE5 

E1 

DDE1 

D1 

F1 

C9 

21FFFF 

18F6 



00260 BIH010 

00270 

00280 

00290 

00300 

00310 

00320 

00330 

00340 

00350 

00360 

00370 

00380 

00390 

00400 

04 10 

00420 

00430 

0440 

0450 

00460 

00470 

004 80 BIN0 15 

0490 

00500 

00520 

00530 

00540 BIH020 

00550 

00560 BIN030 

00570 

00580 BIN035 

00590 

00600 

006 10 

00620 BIN040 

00630 

00640 HI 

00650 LO 

00660 MID 

00670 INCM 

00680 START 

00690 



LD 

LD 

OR 

SBC 

SRL 

RR 

LD 

ADD 

LD 

ADD 

LD 

ADD 

PUSH 

POP 

LD 

LD 

GR 

SBC 

LD 

JR 

JR 

LD 

LD 

LD 

OR 

JR 

JR 

LD 

JR 

PUSH 

POP 

POP 

POP 

POP 

RET 

LD 

JH 

DEFS 

DEFS 

DEFS 

DEFS 

DEFS 

END 



(LO) 
(HI) 



HL.DE 

H 

L 

(INCH) ,HL 

HL.DE 

(MID) , HL 

HL.HL 

DE, (START) 

HL.DE 

HL 

IX 

H, (IX+1 ) 

L,(IX) 

A 

HL.BC 

HL, (HID) 

Z.BIN030 

HCBIN020 

(LO) ,HL 

HL.(INCM) 

A,H 

L 

Z.BIN040 

BIN010 

(HI) , HL 

BIU0 15 

IX 

HL 

IX 

DE 

AF 

HL.-1 

BIH035 

2 



GET LOW VALUE 

GET HIGH VALUE 

CLEAR CARRY 

FIND HIGH-LOW 

KSB/2 

(HI-L0W1/2 

SAVE IHCREMENT/2 

L0+1/2INC 

SAVE MIDPOINT 

HID«2 FOR WORD ADDRESS 

START OF TABLE 

START + MIDPOINT ADD 

PUT IN IX 



;GET MSB BYTE 

;GET LS BYTE 

;CLEAR CARRY 

;TEST VALUE 

[SETUP FOR STORE 

;G0 IF FOUND 

;G0 IF LOW 

;NEW LOW 

;GET INCREMENT 

;0 FOR SMALLEST TEST 

[CLEAR CARRY 

;G0 IF END 

;LOOP 

;NEW HIGH 

[LOOP 
;ADDRESS 
[FOR RETURN 
[RESTORE REGISTERS 



[RETURN 

[DUMMY FOR NOT FOUND 

[GO TO RETURN 



TOTAL ERRORS 



Figure 8-12. Binary Search Routine 



The routine is entered with DE holding the number of 
entries in the table, BC holding the 16-bit search value, 
and HL pointing to the table start. A binary search will be 
made of the table. If the value in BC is found, HL is 
returned with a pointer to the table entry. If there is no 
corresponding table entry, HL is returned with a "not 
found" value of -1. 

Data in this table must be 16-bit unsigned values. All 
compares will be of unsigned data (8000H is greater than 
7FFFH and FFFFH is greater than FFFEH, for example). 
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BINSRC works as follows. Five variables are used — HI, LO, 
MID, INCM, and START. START is simply the table start from 
entry. HI holds the current high index value defining the 
top of the range. LO holds the low index value. MID holds 
(HI-LO)/2 + LO, which points to the next "test" value in the 
middle of the range. INCM is (HI-LO)/2. INCM gets smaller 
and smaller as the search "zeroes in" on a value. 

The routine starts with HI equal to the number of entries 
and LO equal to 0. For each iteration, HI-LO is found, 
divided by two, and added to LO. This gives the index 
value for the comparison. This value is multiplied by two 
and added to START to find the actual table address. 

After the address is found, the table entry is compared to 
the BC search value. If the table value is less, the MIDpoint 
value replaces LO; if the table value is more, the MIDpoint 
value replaces HI. Either way, one half of the current 
range is discarded. 

The "halving" process continues until the search value is 
found (BIN030) or until the increment INCM is zero, 
indicating that HI-LO = 1." (The test is made after the 
comparison.) 

With the proper parameter passing setup, BINSRC could be 
used to search a BASIC integer array, as the array would 
be made up of 16-bit values. Use VARPTR to find the array 
address. 

There are other types of searches, but the binary search 
and sequential searches are the most commonly used in 
assembly language. Many searches use the sequential 
scan since it's the easiest to implement. 
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Sorting 

Now the question arises, "How did the data in a table get 
sorted in the first place?" There are a number of ways you 
can sort data — the brute-force two-buffer sort, bubble 
sorts, binary-insertion sorts, the Shell-Metzner sort, and 
many others. We'll discuss the first two, which should 
handle most assembly-language applications. 

The Brute-Force Two-Buffer Sort 

In this sort we require two buffers. The second is the same 
size as the first. Here you scan the first "buffer," which is 
the table of items to be sorted, sequentially for the 
smallest data item. When it's found, it's put into the 
second buffer in the next position. The item is then 
"blanked out" in the first buffer. 

This sort requires a lot of memory space because of the two 
buffers and is relatively slow because of the complete scan 
required for every item. On the other hand, it's simple in 
concept and easy to debug. 

The assembly-language subroutine for the sort is shown in 
Figure 8-13. Here again, the sort works with 16-bit data 
values. Why 16 bits? The 8-bit case is virtually useless, 
and a version that handles long strings is much more 
complicated. The 16-bit version is complicated enough due 
to 16-bit comparisons that must be done and other un- 
wieldy 16-bit operations. 
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8000 




00100 




ORG 


8000H 








00110 


; IIEfgtllEg fill fi»Ofifl««BJHUH!9»a»8»&«»S»«l!»»S» aeaaaa SB*«*S«»S 






00120 


: fi 


TWO BUFFER SORT OF 16 


- 'IT ENTRIES » 






00130 


;• ENTRY: (IX) = 


BUFFER 1 ADDRESS 


a 






00140 


i * 


(IY) = 


BUFFER 2 ADDRESS 


a 






00150 


• II 


(DE) = 


NUMBER OF ENTRIES 


a 






00160 


;« EXIT 


: BUFFER1 ENTRIES SORTED 


IN BUFFER2. BUFFER1 » 






00170 


; * 


DESTROYED 


a 






00180 


;• NOTE 


: ENTRIES OF ARE NOT ALLOWED • 






00190 


• a 


ALL REGISTERS "DESTROYED 


a a 






00200 


.aaaaBaaaaaaaaaesBBeaafiaaaBaaaeBaBBBaBeBBaaaaaaaaaaaeaBaa 


8000 


DD225B80 


00210 


TWOBUF 


LD 


(BUF1 ! ,IX 


SAVE START 


8004 


ED535D80 


00220 




LD 


(COUNT), DE ; 


SAVE COUNT 


8008 


DD2A5B80 


00230 


TWB005 


LD 


IX,(BUF1) 


:L0AD START 


800C 


210000 


00240 




LD 


HL,0 


;ZERO 


800F 


226180 


00250 




LD 


(CURLOC) ,HL 


; CURRENT LOCATION 


8012 


21FFFF 


00260 




LD 


HL.OFFFFH 


iFOR SMALLEST 


8015 


225F80 


00270 




LD 


(CURVAL) ,HL 


[CURRENT VALUE 


8018 


ED5B5D80 


00280 




LD 


DE, (COUNT) 


;GET COUNT 


801C 


DD660 1 


00290 


TWB010 


LD 


H,(IX+1 ) 


;GET USB 


801F 


DD6E00 


00300 




LD 


L,(IX) 


;GET LSB 


8022 


7C 


00310 




LD 


A,H 


;TEST FOR ENTRY 


8023 


B5 


00320 




OR 


L 




802H 


2811 


00330 




JR 


Z.TWB030 


;G0 IF ZERO 


8026 


ED4B5F80 


00340 




LD 


BC, (CURVAL) 


;GET CURRENT VALUE 


802A 


B7 


00350 




OR 


A 


:CLEAR CARRY 


802B 


ED42 


00360 




SBC 


HL.BC 


: COMPARE 


802D 


3008 


00370 




JR 


HCTWB030 


;G0 IF CURRENT LARGER 


802F 


09 


00380 




ADD 


HL.BC 


;RESTORE NEW VALUE 


8030 


225F80 


00390 




LD 


(CURVAL) , HL 


;NEW SMALLEST 


8033 


DD226180 


004 




LD 


(CURLOC) ,IX 


;NEW LOCATION 


8037 


DD23 


004 10 


TWB030 


INC 


IX 


; POINT TO NEXT 


8039 


DD23 


00420 




INC 


IX 




803B 


1B 


00430 




DEC 


DE 


; DECREMENT COUNT 


803C 


7A 


00440 




LD 


A,D 


;TEST FOR ZERO 


803D 


B3 


00450 




OR 


E 




803E 


20DC 


00460 




JR 


NZ.TWB010 


;G0 IF NOT END 


8040 


2A6180 


00470 




LD 


HL, (CURLOC) 


;GET CURRENT LOCATION 


80fl 3 


7C 


0480 




LD 


A, H 


;TEST FOR 


80U1) 


B5 


00490 




OR 


L 




8045 


C8 


00500 




BET 


Z 


;RETURN IF ALL BLANKED 


801)6 


AF 


00505 




XOR 


A 


;ZERO TO A 


80117 


3E00 


00510 




LD 


A,0 


;0 TO A, DON'T SET CARRY 


8049 


77 


00520 




LD 


(HL) ,A 


;BLANK ENTRY 


804A 


23 


00530 




INC 


HL 




eoitB 


77 


00540 




LD 


(HL),A 




8011C 


2A5F80 


00550 




LD 


HL, (CURVAL) 


;GET CURRENT VALUE 


804F 


FD7401 


00560 




LD 


(IYi-1) ,H 


; STORE MSB 


8052 


FD7500 


00570 




LD 


(IY) ,L 


;STORE LSB 


8055 


FD23 


00580 




INC 


IY 


iBUMP BUFFER2 PNTH 


8057 


FD23 


00590 




INC 


IY 




8059 


18AD 


00600 




JR 


TWB005 


[CONTINUE 


0002 




00610 


BUF1 


DEFS 


2 




0002 




00620 


COUNT 


DEFS 


2 




0002 




00630 


CURVAL 


DEFS 


2 




0002 




00640 


CURLOC 


DEFS 


2 




0000 




00650 




END 






OOOOC 


TOTAL ERRORS 











Figure 8-13. Two-Buffer 
Sort Routine 

The routine is entered with IX and IY pointing to the two 
buffers. IX points to the buffer containing the unsorted 
data; IY points to a second buffer holding the sorted data. 
As the entries in the IX buffer are moved to the IY buffer, 
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they are "blanked" by filling with a zero value. For this 
reason, zero is not a valid value in the IX buffer, unless 
you'd like it to be ignored. 

DE contains the number of entries in each of the buffers. 
The routine first scans the IX buffer until it finds the 
smallest entry. A dummy count of OFFFFH is initially put 
in variable CURVAL to guarantee that a smaller entry will 
be found. Each entry in the IX buffer is compared with the 
smallest entry. At the end of the scan, the smallest entry 
is in CURVAL and its address is in CURLOC. The entry is 
now blanked by filling its position with 0000H. The entry is 
then stored in the next position in the IY buffer. The 
process is repeated until all entries in the IX buffer have 
been blanked. Figure 8-14 shows the sort action. 



(IX). 




17 



19 



BUF2 + 

+ 2 
+ 4 



17 



512 



333 



222 



+ N-2 
+ N 



+ N-2 
+ N 



CONTAINS UNSORTED 

2-BVTE ENTRIES 



CONTAINS SORTED 
ENTRIES AT COMPLETION 



Figure 8-14. Two-Buffer Sort 
Action 
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Two-Buffer Sort Speed and Storage 

The two-buffer sort is very expensive in terms 
of memory storage since it must use another 
buffer the same size as the first to do its 
dirty work. How fast is it? Because the sort 
must pass completely through the first buffer 
for each entry, it requires n passes to sort, 
where n is the number of entries. Each 
iteration requires approximately 35 
instructions. If we estimate about 5 
microseconds per instruction, that means each 
pass takes about 175 microseconds. For a 
thousand entry table, this is a little under a 
fifth of a second. Quite a difference from 
BASIC - we can afford to be ' 'sloppy' ' in 
high-speed code such as this. Nevertheless, 
many sorts are run ''off-line'' in commercial 
programming departments during hours when only 
the maintenance crew is around. 



The Bubble Sort 

The "bubble" sort is another sorting technique. It uses 
only one buffer and is therefore efficient in memory 
storage. The bubble sort works with two entries of the 
table at a time. It switches the entries if the second entry 
is of lower value than the first. In this way, the "lighter" 
entries bubble to the top. After each pass through the 
table, another pass is made. If no switches have occurred 
after any pass, the sort is done (See Figure 8-15). 
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Figure 8-15. Bubble Sort Action 



The assembly-language code for the bubble sort is shown 
in Figure 8-16. The bubble sort is an elegant, clean code 
but is somewhat slow for all its grace. Pass after pass is 
made through the buffer, and each adjacent set of entries 
is compared. If the "top" element is larger than the 
"bottom," the two are swapped. A change flag (CHNG) is set 
if any swap is made. If no swap has been made in any pass, 
the swapping is over, and the sort is done. The BUBBLE 
routine here is a good example of the power of indexing. 
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The BUBBLE routine is a great one to run with the contents 
of the buffer equated to video display memory if you'd like 
to see a graphic example of the sorting process. Set IX 
equal to 3C00H and DE equal to 200H (there are two bytes 
per entry). You'll have to call the routine from another bit 
of assembly-language code, or "dummy up" a CALL from 
DEBUG, such as CD 00 80 C3 03 AO (CALL 8000H and 
Endless Loop at A003H). 



8000 




00100 




ORG 


80O0H 








001 10 


; llll«l 


Ell«llli 


iiBieitiRDiiaiglifii 


BBflSBfifiaaaBBflBfiBflBflBfifl 






00120 


> B 




BUBBLE SORT 


* 






00130 


•» ENTRY: (IX) 


^BUFFER 


B 






00140 


■- G 


(DE) 


=NUMBER OF ENTRIES IN 16-BIT ENTRY TABLE * 






00150 


•» EXIT: BUFFER CONTAINS SORTED ENTRIES » 






00160 


;• ALL 


REGISTERS "DESTROYED* 


B 






00170 


.BfiBBflBasfiBBsBSfiBaBfiBBBflfifissBfififlBBSBSBssBssasflBBBflBssflfiBfl 


8000 


DD224A80 


00180 


BUBBLE 


LD 


(BUFFER) ,IX ;SAVE START 


8004 


IB 


00190 




DEC 


DE ; DECREMENT COUNT 


8005 


ED534C80 


00200 




LD 


(COUNT), DE ;SAVE FOR PASSES 


8009 


AF 


00210 


BUB010 


XOR 


A 


"CHANGE" FLAG 


800A 


324EB0 


00220 




LD 


(CHNG) ,1 


TO ZERO 


800D 


ED4B4C80 


00230 




LD 


BC, (COUNT) 


LOAD #-1 


8011 


DD2A4A80 


00240 




LD 


IX, (BUFFER) 


GET START OF BUFFER 


8015 


DD6601 


00250 


BUB015 


LD 


H.CIX+1 ) 


:GET MSB OF FIRST 


8018 


DD6E00 


00260 




LD 


L.(IX) 


:GET LSB OF FIRST 


801B 


DD5603 


00270 




LD 


D, (IX+3) 


;GET MSB OF SECOND 


801E 


DD5E02 


00280 




LD 


E, (IX+2) 


:GET LSB OF SECOND 


8021 


B7 


00290 




OR 


A 


;RESET CARRY 


8022 


ED52 


00300 




SBC 


HL.DE 


; COMPARE BY SUB 


8021 


2814 


00310 




JR 


Z.BUB02O 


;DON'T SWAP IF EQUAL 


8026 


3812 


00320 




JR 


C.BUB020 


;GO IF FIRST SMALLER 


8028 


19 


00330 




ADD 


HL.DE 


;RESTORE HL 


8029 


DD7201 


00340 




LD 


( IX+1 1 ,D 


;SWAP FIRST WITH SECOND 


802C 


DD7300 


00350 




LD 


(IX), E 




802F 


DD7403 


00360 




LD 


(IX+3J ,H 




8032 


DD7502 


00370 




LD 


(IX+2),L 




8035 


3E01 


00380 




LD 


A, 1 


:N0N-ZEB0 


8037 


324E80 


00390 




LD 


(CHNG) , A 


:SET CHANGE FLAG 


803A 


DD23 


00400 


BUB020 


INC 


IX 


;BUMP PNTR 


803C 


DD23 


004 10 




INC 


IX 




803E 


OB 


004 20 




DEC 


BC 


;DECREMENT COUNT 


803F 


78 


00430 




LD 


A,B 


iTEST COUNT 


80H0 


B1 


004 4 




OR 


C 




804 1 


20D2 


00450 




JR 


NZ.BUB015 


;GO IF NOT LAST 


8013 


3A4E80 


00460 




LD 


A, (CHNG) 


GET FLAG 


80116 


B7 


00470 




OR 


A 


TEST CHANGE 


8047 


C8 


00480 




RET 


Z 


RETURN IF NONE 


8048 


1BBF 


00490 




JR 


BUB010 


AT LEAST ONE CHANGE 


0002 




00500 


BUFFER 


DEFS 


2 




0002 




00510 


COUNT 


DEFS 


2 




0001 




00520 


CHNG 


DEFS 


1 




0000 




00530 




END 






00000 TOTAL ERRORS 











Figure 8-16. Bubble Sort 
Routine 



182 



Hints and Kinks 8-6 ■ 



Bubble Sort Speed and Storage 

The bubble sort is very efficient in terms of 
memory storage since it works within the given 
buffer and uses very little storage elsewhere. 
It's a good sort to use when space is at a 
premium. 

However, speed can be another matter. There is 
no fixed number of iterations through the 
table with a bubble sort. The best case would 
be one pass, when all entries are already 
sorted. The worst case (I believe) is the case 
where the entries are completely reversed with 
the ' 'lighter' ' elements at the bottom of the 
table, water-sogged. If even one element in 
the table must be moved from bottom to top, it 
will take n-1 iterations, where n is the size 
of the table in entries. A rough estimate of 
the time for our bubble sort would be 25 
instructions per iteration at 5 microseconds 
per instruction, or 125 microseconds per 
iteration. Moving one element from bottom to 
top in a 1000-entry table would require about 
an eighth of a second. (Still not bad compared 
to BASIC . . , . ) 



There are a number of other sorts that could be used in 
assembly language, but they're somewhat more complex to 
code and should be used only if you'd really like to crank 
out every last bit of speed in your assembly-language 
sorting. Hopefully these sorts have whetted your interest. 
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Chapter Nine 



Graphics Display Processing 



Several chapters ago we looked at some of the techniques 
used to display character data on the screen. Here, we'll 
talk about graphics display processing — how to put 
graphics characters on the screen, how to draw shapes and 
lines, and how to "animate" screen images. 



Graphics Characteristics 
Character Data Storage 

Most of you are familiar with the scheme used in the 
TRS-80 for displaying graphics, but we'll go over it again 
before we talk about graphics processing. There're 1024 
character positions on the screen, arranged in 16 lines of 
64 characters each. In the "upper case" version of the 
TRS-80, video memory stores only seven bits of data for 
each character stored. As a matter of fact, all character 
data must have the most significant bit, (bit 7), set to 0, so 
the video memory only uses six bits to represent the ASCII 
character codes. The "missing bit" is bit 6. Figure 9-1 
shows how the 64 valid ASCII codes are stored in memory. 
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CHARACTER 


ASCII 


MEMORY* 


CHARACTER 


ASCII 


MEMORY* 


SP 


10 H 


20 H 


@ 


40H 


00 H 


j 


21 


21 


A 


41 


01 


i) 


21 


22 


B 


42 


02 


# 


23 


23 


C 


13 


03 


$ 


24 


1H 


D 


44 


04 


% 


25 


15 


E 


45 


05 


& 


26 


26 


F 


46 


0f& 


' 


27 


27 


G 


47 


07 


( 


28 


28 


H 


4fi 


08 


) 


29 


24 


1 


49 


09 


* 


2A 


2A 


J 


4A 


0A 


+ 


2B 


2B 


K 


MB 


0B 


f 


2C 


2C 


L 


4C 


0C 


- 


2D 


2D 


M 


ID 


0D 




ZE 


2E 


N 


4E 


0E 


/ 


2F 


2F 


O 


4F 


0F 





30 


30 


P 


50 


10 


1 


31 


3! 


Q 


51 


II 


2 


31 


32 


R 
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12 


3 


33 


33 


S 


53 


13 


4 


34 


34 


T 


54 


14 


5 


35 


2S 


U 


55 


IS 


6 


36 


36 


V 


56 


16 


7 


37 


37 


W 


57 


17 


8 


38 


38 


X 


58 


18 


9 


39 


34 


Y 


59 


19 




3A 


JA 


Z 


<5A 


IA 


> 


3b 


3B 


t 


x?B 


IB 


< 


3C 


3C 


1 


«5C 


IC 


= 


3D 


3D 




5D 


ID 


> 


3E 


3B 


-» 


JE 


IE 


? 


JF 


3F 


^^BB^ 


5F 


IF 



•MEMORY IS UPPER CASE WITHOUT LOWER-CASE OPTION 

Figure 9-1. Video Memory Codes 

When the video memory byte holding character data is 
read, the memory form of the data is converted back to 
ASCII by setting bit 6 if bit 5 AND bit 7 are Os. Since bit 7 is 
never set for character data, the video-memory codes are 
reconverted back to ASCII as shown in Figure 9-2. 
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ASCII CODE 
FOR "J" 


0\ \\0\0\ 10 10 




\ L n n 
NAND 


it it h u 


VIDEO MEMORY 
CODE FOR "J" . 





•Xi 


00 


i 





! 






7 6 5 4 3 2 10 



BIT 7 ALWAYS 9 FOR 

ASCII 

BIT 6 NON-EXISTENT 

IN UPPER CASE ONLY 

"NAND" MEANS THAT BIT 

6 WILL BE A 1 IF BIT 

7 AND BIT 5 ARE 
BOTH ZEROES 



Figure 9-2. Reconversion From 
Video Memory 



When character data from 00000000 through 00011111 
(the control codes) or from 01100000 through 01111111 
(lower case) are stored in video memory, they lose bit 6 
and become the characters shown in Figure 9-1. Attempt- 
ing to store codes through 127 results in reading back 2 
sets of the 64 valid character codes. The moral to this long 
tale is "Never store anything in upper case video memory 
except ASCII data (or graphics data, as we'll see) unless you 
want it to be converted to ASCII!" 
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Lower Case Modification 

The lower case modification adds another RAM 
chip to the video memory and a new character 
generator chip. The RAM chip adds an eighth 
bit and eliminates the special video memory 
storage codes; all data is then stored in 
video memory in 8-bit format. The NAND logic 
for bit 6 is also deleted. 



187 



Storage of Graphics Data 

Graphics data is stored exactly the same as character 
data. Bit 6 is lost in upper case versions of the TRS-80. 
However, here bit 7 is set to indicate that the data does 
not represent 64 ASCII-like codes, but 64 graphics con- 
figurations. The graphics configurations allowed are 
shown in Figure 9-3, along with their data values. 
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Figure 9-3. Graphics Codes 



When the data is read back from video memory for 
refresh (hardware display of memory on the screen), the 
CPU hardware logic examines bit 7 to see if it's a or 1. If 
it's a zero, the 6 bits are input to a graphics character 
generator chip that converts the 6 bits to a 5 by 7 gra- 
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phics character. If it's a one, the character generation is 
disabled, and each of the six bits produces one pixel worth 
of data, on or off, as shown in Figure 9-4. 



Hints and Kinks 9-2 

Aspect Ratio 

In graphics work, be certain to plot lines and 
figures using video display worksheets or 
graph paper that shows the correct ''aspect 
ratio' ' of pixels , 

Approximate Relationship (Within 15% Error): 

2 UNITS 
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6 UNITS ■< 













I UNIT 



ONE PIXEL 



2 UNITS 



ONE CHARACTER POSITION 



THIS BIT IGNORED 
(OR NON-EXISTENT) 



THIS BIT A ONE 
FOR GRAPHICS 




BIT0 

• — 



BIT 2 

m 



BIT 4 



BIT1 



BIT 3 

i p 



BIT 5 



BYTE FROM 
VIDEO MEMORY 



7 6 5 4 3 2 1 
BIT 



Figure 9-4. Pixel Representation 
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As each character position on the screen is divided into six 
pixels, there are 1024*6 = 6144 pixel positions on the screen, 
divided into 128 columns and 48 rows, as shown in Figure 
9-5. 




Figure 9-5. Graphics and 
Character Positions 

Character Position and Pixel Addressing 

We saw in Chapter 7 that it's very easy to output char- 
acter data to the screen. The ASCII character you want to 
display is simply stored in the proper character position. 
Compute the character-position address by adding the 
character position number through 1023 to the address 
of the start of video memory, 3C00H. 

Even when you plan to store a character at a specific line 
and character position within a line, the address compu- 
tation is simple. The formula for a video-memory address 
for a line character-position address is: 

ADDRESS = LINE*64 + CHAR PCS + 3C00H 

where LINE is the line number through 15 and CHAR POS 
is the character position within the line through 63. 
Addressing pixels, however, isn't that easy. As a matter of 
190 



fact, it's a chore due to the memory mapping of the video 
memory. As our seven-year old TRS-80 afficianado puts it, 
"Six into eight don't go!" 

Random addressing of pixels requires an x,y address, 
where x = through 127 and y = through 47. This is 
familiar to most readers as the BASIC SET/RESET format. 
Each pixel is in one of the 1024 bytes of video memory; 
within the byte, the pixel may be in bit positions 
through 5. The task in addressing a pixel is to compute the 
byte address of the byte containing the pixel, followed by 
the bit address of the pixel within the byte. 

If we do some thinking about this problem, we can see that 
the byte address is given by: 

BYTE ADDRESS=3C00H + (Y/3)Q*64 + (X/2)Q 

This formula says if we take the Y address and divide by 
three, the quotient (Q) will represent the line number (.0 
through 15) containing the -pixel. Multiplying this line 
number by 64 will give the displacement from the start 
of video memory of the line. If the X address is divided by 
two, the quotient will give the character position con- 
taining the pixel along the line. The actual byte address is 
now 3C00H + line displacement + character displacement. 

We now have the byte address, but what about the bit 
address within the byte? The row address is given by: 

BIT ADDRESS = (Y/3)R*2 + (K/2)R 

The remainder (R) of Y/3 gives the row number of the bit. 
Since there are two bits per row, this must be multiplied 
by two to give the row displacement. The remainder of X/2 
gives the column number of the bit. Adding this to the 
row displacement gives the bit position through 6 of the 
bit. 

The formulas above are not easy to visualize, but if you 
draw a sketch of the screen showing character positions 
and pixel positions and try some examples, you'll see how 
they were derived. Figure 9-6 shows a recap of pixel 
addressing. 
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Hints and Kinks 9-3 



Higher Speed SET/RESET 



Is a higher-speed SET/RESET possible? A brute 
force method might employ a table look up 
indexed by Y*128 + X. Each entry in the table 
would be a byte address of 0-1023 and a bit 
address of 0-7. This could be stored in two 
bytes, and the entire table would require 
6144*2 = 12288 bytes. 

You could modify this table scheme on a line 
basis by dividing Y by 16 (easy to do) and 
finding ( Y/ IB ) R*12B+X . This index would 
access a 384-entry table of two bytes each 
(1068 bytes) containing the byte address and 
bit address. The actual byte address could be 
found by: TABLE BYTE ADDRESS + (Y/3)Q*G4 + 
3C00H. 

Estimated speed for this SET/RESET would be 
somewhere around 7500 points per second. 




X=127, Y = 47 



COL#0I 

1 LINE #= X QUOTIENT (EACH UNE OF 16 HAS 3 ROWS OF Xsl 

3 

2 ROW # OF CHARACTER = -*- REMAINDER (ROW # WITHIN THE CHARACTER! 

3 

3. CHARACTER POSITION = -*- QUOTIENT (FROM START OF UNE) 

2 

4. COLUMN # OF PIXEL = -*• REMAINDER (0 OR 11 

2 

5. BYTE DISPLACEMENT FROM START OF VIDEO MEMORY = (LINE #)«64 + CHARACTER POSITION 

6. ACTUAL LOCATION = (UNE #).64 + CHARACTER POSITION • 3C00H 

7. BIT POSITION WITHIN CHARACTER = (ROW #)• 2 + COLUMN NUMBER 

Figure 9-6. Pixel Addressing 
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Random Vs. Character Position Graphics 

There are two basic methods of writing out graphics data 
to the screen: "character position" graphics and "random" 
graphics. 

In random graphics, a point is addressed by its x,y 
coordinates and either set, reset, or tested. This method of 
displaying graphics data requires a graphics driver pro- 
gram to convert the x,y coordinates into a byte and bit 
address as we discussed above. Random graphics are used 
for plotting, animation, line drawing, and the like. 

There's a lot of graphics display work, however, that can 
be done by character-position-oriented graphics. This still 
involves setting pixels, but the pixels are not addressed 
randomly. The pixel positions to be set (or reset) are 
known beforehand, and data is output on a character 
position basis to produce the graphics. 

We'll discuss these methods before getting into the more 
complicated random techniques. 



Character-Oriented Graphics 

Horizontal and Vertical Line Drawing 

The simplest graphics processing involves drawing a 
horizontal or vertical line. Since there are three rows in a 
graphics character position, the horizontal line height can 
be either 1/3, 2/3, or 3/3 of a character position height. The 
width of a vertical line can be 1/2 or 2/2 of a character 
position width. 

Figure 9-7 shows some code from the MORG program of 
Chapter 13 that draws a thick line across line 12 of the 
screen. LINE 12 is equated to 3F00H. The FILLCH (Fill 
Character) subroutine is used to fill an 8FH for 64 bytes, 
starting at 3F00H. 
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8026 3E8F 00470 

8028 11003F 00480 

802B 014000 00490 

802E CD8385 00500 



LD A.OBFH 

LD DE.LINE12 

LD BC.64 

CALL FILLCH 



;ALL ON GRAPHICS CHAR 

;LME 12 

;t OF BYTES 

;DRAW LINE 



Figure 9-7. Horizontal Line 
Drawing 

When you need to draw a vertical line, the process is 
similar, except that the "increment" is 64 instead of one. 
This sets the next character position under the last to 
draw the line vertically. Code for drawing a vertical line is 
shown in Figure 9-8 from the DRAWL subroutine of 
Chapter 14. The graphics character to be used is in the A 
register. 









00350 


jVERTICAL LINE 


HERE 




000F' 


Fl 




00360 


DRA060: POP 


AF 


:REST0RE CHARACTER 


0010 ' 


11 


0040 




LD 


DE.64 


; INCREMENT 


0013' 


77 




00380 


DRA065: LD 


(HL) ,A 


;STORE GRAPHICS 


0014 ' 


19 




00390 


ADD 


HL.DE 


■.POINT TO NEXT 


0015 ' 


10 


FC 


00400 


DJNZ 


DRA065 


;G0 IF MORE 



Figure 9-8. Vertical Line 
Drawing 

If you're doing a large amount of line drawing in a pro- 
gram, then it'd be convenient to automate the process 
somewhat. One approach is to make a table of lines to be 
drawn. This makes it easy to define new displays and to 
correct existing ones (another example of a "table-driven" 
approach). 



■Hints and Kinks 9-4 ■ 
Graphics Driver 



A table-driven ' 'line drawer' ' could be 
expanded even further. A graphics driver 
subroutine could decode such table entries as 
' 'draw horizontal line, ' ' ' 'draw vertical 
line, ' ' ' 'draw rectangle with given corners, ' 
' 'draw filled in box, ' ' ' 'draw diagonal 
line, ' ' and so forth. This would be a useful 
program if you continually do display work, 
but probably not worth the time otherwise. 
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We used this method in Chapter 14 for the Tic-Tac-Toe 
program. The programmer used a "grid table," GRIDT, to 
define all the lines to be drawn in the Tic-Tac-Toe grid. 
(There were more than four lines, due to some segments 
that occupied less than a character position.) 

Each entry in the GRIDTB is five bytes long (see Figure 8-4) 
and defines the graphics character to be used (one byte); a 
code for horizontal/vertical (one byte); the number of 
character positions to be used (one byte); and the line 
starting position (two bytes). The table is terminated by a 
minus one. The DRAWL subroutine shown in Figure 9-9 is 
called for each entry in the table to draw a single line, 
horizontal or vertical. 

Although the routines here involved only setting pixels, 
it's easy to see how codes for resetting pixels could also be 
incorporated into code or table-driven routines. 

Resetting the pixels could be done either by clearing the 
screen with graphics 80H characters (about l/25th second) 
and redrawing a new line or by going back over the old 
line with a "fill" byte of 80H. The routines above allow 
horizontal or vertical lines to be drawn at rates of about 
3000 lines per second (assuming average line lengths of 20 
character positions) which would permit fast game dis- 
plays or other display processing. 
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Drawing Patterns and Figures 

You can also use graphics done on a character-oriented 
basis to draw patterns or figures. In this case, you must 
"plot" the figure on a display worksheet or graph paper, 
convert it to the proper graphics code, and then output it 
to the correct character positions. 

One of the programming problems that seems to come up 
time and time again is display of "large format" char- 
acters. The Tic-Tac-Toe program of Chapter 15 uses large 
characters for messages, and it's frequently done in other 
game programs. Let's look at the techniques involved in 
this program; it'll illustrate the general approach for dis- 
playing other types of patterns. 

The first task in producing patterns such as alphanumeric 
characters is to draw out the patterns to be displayed. 
Figure 9-10 shows a typical pattern for the "large char- 
acters" used in Chapter 14. Each character is an 8 by 6 
matrix. The pixels are filled in to produce a pleasing 
alphabetic or other character. You could use any size 
matrix, but a multiple of two works out conveniently for 
the horizontal dimension while a multiple of three works 
out nicely for the vertical dimension, due to the 2 by 3 
mapping of pixels to a character position. 



Hints and Kinks 9-5 



Large Character Format 
The approach of defining a matrix of dots to 
represent alphanumeric and special characters 
is used to generate characters for video 
displays, dot matrix printers, and the like. 
Reference descriptions of ''character 
generator' ' chips to find characters already 
defined in 5 by 7, 6 by 8, and other formats. 
You can then easily convert them to tables 
such as the one used in the Tic-Tac-Toe 
Program, saving you the work of drawing them 
out manually. 
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Figure 9-10. "Large" Character 
Pattern 

After you've established the pattern, you convert it to a 
graphics-character data value. In this case, there are four 
graphics characters horizontally and two vertically (a total 
of eight). Each graphics character is then converted to 
eight bytes as shown in Figure 9-11. 
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Figure 9-11. Pattern Conversion 
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Now the eight bytes per character are stored in a table. If 
the patterns have some numerical sequence, you may store 
them in logical fashion, such as through 9. In this case, 
the characters were stored from A through Z, followed by 
space, -, ?, and !. A second table, CTAB, then holds the ASCII 
equivalent in the same order, as shown in Figure 9-12. To 
locate any character data, CTAB is first scanned for the 
character. When it is found, its index is multiplied by 8 to 
give the location of the character data in DOTTAB. 
Character data in DOTTAB doesn't have the most 
significant bit set; it's set in the graphics driver rou- 
tine (LARGEC). 



CTAB 


A 


DOTTAB 

DOTTAB +8 

+ 16 

+ 24 

INDEX 

DOTTAB + 
239 

9-12. CTA 
Relations 


8 BYTES FOR "A" 
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D 






E 








1 T 




T 






U 






V 






w 






X 






Y 






2 






SPACE 






- 






? 




CTAB +29 


I 


8 BYTES FOR « i " 


Fig 
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Outputting a large-format character proceeds like so: 

1. Search CTAB for the character. 

2. Use the CTAB index*8 to find the character data in 
DOTTAB. 

3. Output the first four bytes from DOTTAB to a screen 
character position start through start + 3. 
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4. Output the next four bytes from DOTTAB to the 
screen start + 64 through screen start + 67. 

The LARGEC subroutine from Chapter 15 is shown in 
Figure 9-13. It uses the steps above to output a large 
character to a given screen position. A contains the 
character to be output in ASCII, while IY contains the 
screen address. In use, you would write an ASCII character 
string to the screen by repeated calling of LARGEC with the 
next ASCII character. Between calls, the screen pointer is 
incremented by two to provide spacing between characters. 
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The MATSR subroutine within LARGEC writes out four 
bytes for the row. It is called twice, once with the screen 
start address, and once with the screen start address + 64. 
The remainder of the logic in the program involves 
searching CTAB and accessing DOTTAB. 



COOO F5 
C001 5C 
C002 7D 
C003 CB3B 
C0Q5 1600 
COOT 3-001 
C009 U 
C00A 06FF 
C00C OH 
C00D D603 
CO0F F20CC0 
C012 C603 
C011 07 
C015 82 
C01& IF 
C017 68 
C018 2600 
C01A 0606 
C01C 29 
C01D 10FD 
COIF 1600 
C021 19 
C022 110O3C 
C025 19 
C026 0600 
C028 F1 
C029 B7 
C02A 200C 
C02C DD2144C0 
C030 DD09 
C032 7E 
C033 DDE600 
C036 77 
C037 C9 
C03S DD214AC0 
CQ3C DD09 
C03E IE 
C03F DDA600 
C012 18F2 
C044 81 
C045 82 
C046 8« 
C047 88 
C048 90 
C049 A0 
C04A FE 
C04B FD 
C04C FB 
C01D FT 
C04E EF 
C04F DF 
0000 
00000 TOTAL £ 



00100 
00400 
004 10 
004 20 
004 3 
00440 
004 50 
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004 90 
00500 
00510 
00520 
00530 
00540 
00550 
00560 
00570 
00580 
00590 
006 
06 10 
0620 
00630 
00640 
00650 
00660 
00670 
00680 
00690 
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00840 
00850 
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00870 
00880 
00890 
00900 
009 10 
00920 
00930 
00940 
00950 
00960 
00970 
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ORG 



0C0OOH 



SUBROUTINE TO SET OR RESET 
IN H REGISTER AND I (0-47) 
(A)=0 FOR SET, ! FOR RESET 



A PIXEL GIVEN X (0-127) 
IK L REGISTER. 



SET10 

SET20 



SET36 
RESET 



PUSH 

LD 

LD 

SHL 

LD 

Jfi 

INC 

LD 

INC 

SOB 

JP 

ADD 

HLCA 

ADO 

LD 

LD 

LD 

LD 

ADD 

DJNZ 

LD 

ADD 

LD 

ADD 

LD 

POP 

OR 

JS 

LD 

ADD 

LD 

on 

LD 

RET 

LD 

ADD 

LD 

AND 

JR 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

END 
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A, L 

E 

D,0 

KC.SET10 
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B, OFFH 



P,SET20 

A, 3 

A,D 
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B,6 

HL,HL 

SET30 

D,0 

HL.DE 

DE.3CO0H 

HL.DE 

B, 
AF 
A 

H I , R ES E T 
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( IX) 

SET36 
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88H 

90H 
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OFDH 
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0F7H 

OEFH 

ODFH 
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[BUMP QUOTIENT IK B=LINEt 
(SUCCESSIVE SUBT FOR f} 
;C0 IF HOT NEGATIVE 
;ADD BACK FOR REMAIN DER. SOMI 
; ( ROW#)»2 

; ( ROWf )»2*COL*=BIT POS 
jSAVE BIT POS IN C 
[LINE # 
;NOH IK HL 
;SHIFT COUNT 

;MULTIPLY LIKE»«64 
iLOOP TIL DONE 

DE NOW HAS CHAR POS 

(LINE<)»64*CHSR POS IN HL 

START OF VIDEO 

(LINE#) »64*CHAR P0S-3C00H 

BC NOW HAS BIT POS 

GET SET/RESET FLAG 

TEST FLAG 

00 IF RESET 

START OF MASK TABLE 

POINT TO MASK 

LOAD PIXEL 

SET PIXEL 

STORE IN VIDEO 

RETURN 

RESET MASK TABLE 

POINT TO MASK 

LOAD PIXEL 

RESET PIXEL 

GO TO STORE, BETURK 

MASK TABLE 



Figure 9-14. SETRST 
Routine 
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Drawing Random Points 

Now let's get back to the problem of setting and resetting 
random points. We know from our previous discussion how 
to compute the bit and byte address of the pixel, given an 
x,y coordinate. Figure 9-14 shows a subroutine that will 
set or reset any given pixel. Entry is made with X (0 
through 127) in H and Y (0 through 47) in L. The A register 
is for a set function and 1 for a reset function. 

First compute the address of the byte containing the pixel 
by the algorithm previously described. Then use the bit 
position to access a "mask" table of one of six entries. 
There are two mask tables: one for setting a pixel; one for 
resetting a pixel. The byte containing the pixel is then 
ANDed with the mask and stored again to set or reset one 
of the six pixel bits in the byte location. 



You should have first set all character positions that are to 
be used for graphics to a graphics "null" character 80H to 
ensure that graphics mode and not character mode is in 
force. 



Hints and Kinks 9-6 



If an 80H is Not Used . . . 

If you attempt a SET/RESET for a pixel in a 
character position that has not been 
initialized by 80H, strange results may occur 
in an upper case TRS-80 . A blank character 
position could have either 20H (ASCII space) 
or 80H (graphics null) in video memory. If it 
has 20H, attempting to SET a point and then 
turning on bit 7 results in 101X XXXX, where X 
is the pixel that has been set. This results 
in two pixels being displayed, one for the SET 
and one from the 20H! Always clear the area to 
be used for graphics with 80H before display 
work! 
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Animation 

This routine takes about 400 microseconds to set or reset a 
pixel, making the number of pixels that can be processed 
per second about 2500. This is 20 times or so faster than 
SET/RESET in BASIC, but still somewhat slow for truly high- 
speed processing. If a "frame" of a picture was all 6144 
pixels, for example, then only one third of a frame per 
picture could be processed per second. That's also assum- 
ing that no other "number-crunching" was being done. 

Of course, if the number of active pixels per frame is 
fewer, then we can process something close to animation 
rates of 16 frames per second. If each new frame of data 
RESET one half of the points and SET a number of points 
equal to half on the screen, we'd be SETting and RESETting 
the average number of points per frame, then, for each 
frame. If we can process 2500 points per second, that gives 
us about 156 points per frame, which is somewhat sparse 
for many pictures, but about the best that can be done. 
Another problem here is obtaining the data base for the 
animation. (The thought of digitizing 100,000 points for 
40 seconds worth of Star Warp, or some other game, gives 
me pause . . . .) 

Line Drawing 

We've discussed the simple procedures of drawing hori- 
zontal and vertical straight lines, but how about angled 
lines? 

The BASIC approach to this problem would undoubtedly 
involve trigonometry and be very slow. However, there is 
a non-trigonometric approach that would work well in 
assembly language to permit high-speed processing. The 
one we'll illustrate here involves minimum math and a 
somewhat different approach, so bear with us — it'll be 
fairly high speed and worth the effort. 

Figure 9-15 shows a line on the TRS-80 screen. It starts in 
the upper left and is drawn diagonally at a shallow angle. 
The distance from XI to X2 is equal to some "delta X" 
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expressed in pixel units. In this case, XI is 10, X2 is 20, 
delta X is 20-10 or 10 units. The distance from Yl to Y2 is 
equal to some "delta Y," expressed in the same units. In 
this case delta Y is 21-15, or 6 units. 
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If we SET a point at every X value — 10, 11, 12, 13, 14, 15, 
16, 17, 18, 19, and 20 — what points would have to be set 
for Y values? We can easily find out by computing the 
amount that Y has to be incremented for every new X 
position. This is: 

DELTA Y/ DELTA X = 6/ 10 PIXEL 

In other words, every time we increment X by 1, we 
increment Y by .6. The points that would be set for this 
line would therefore be: 

X Y X Y 
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Notice that we wrote some points more than once, but at 
least the algorithm is straightforward. 

There is a minor problem here — how do we work with 
fractions in assembly language? In BASIC we have the 
mechanism built into a FOR . . . TO . . . STEP loop. How do we 
implement it here? 
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Scaling 

We'll scale Y upwards by 256. This means we'll hold Y as a 
number multiplied by 256. The high-order 8 bits will be 
the integer portion of the number, and the low-order 8 bits 
will be the fractional part, as shown in Figure 9-16. When 
we find delta Y/delta X, we'll get a result that is actually 
(delta Y*256)/X as shown in Figure 9-17. We can then add 
the result to the 16-bit scaled representation of Y to get 
each new increment of Y. After every add, we'll take the 
new value of X and the integer (higher 8 bits) of Y to set 
the new point. The whole process for the points we've been 
discussing is shown in Figure 9-18. 



HIGH-ORDER 8 BITS 


LOW-ORDER 8 BITS 


INTEGER PORTION 
OFY 


FRACTIONAL PORTION 
OFY 



Figure 9-16. Scaling Example 



X = 10,Y=15 



»X = 20,Y = 21 



AX = 20 -10=10 
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AY*256 = 6*256 =1536 

AY*256/AX = 153.6 -<- 154 (ROUNDED UP) 
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6*256 = 1536 



1536/10=154 
(ROUNDED) 



Figure 9-17. Scaling With 
Division 
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4148+154 = 4302. 


Ife 


It 


000I00J2H 


1 1 I 000 


4302+ 154= 4456 


17 


15 


00010010 


000000 1 


4456+154= 4610 


18 


16 


00010010 


I 00 I I I00 


^610+154= 4764 


18 


17 


0001 0011 


00 I lOI 10 


47fe4+IS4= 4418 


i"? 


18 


000100 1 1 


I IOIOOOO 


4<? 18+ 154= 5072 


19 


11 


000101 00 


Ol IOIOI0 


5072+154 = 52.26 


20 


20 


0001 0101 


OOOOOIOO 


5226+154 = 5380 


21 



Figure 9-18. Basic Line Drawing 
Algorithm 



Hints and Kinks 9-7 

Scaling 

The problem of scaling was not a trivial one 
in early computer work. {Digital Computer 
Programming by McCracken, 1957, devotes a 
chapter to ''Decimal Point Location 
Methods. ' ' ) Higher-level languages solved the 
problem of working with mixed numbers, and 
most ''number crunching'' applications use a 
language other than assembly language to avoid 
laborious scaling processing. 



Now this algorithm works fine for the one case we've been 
discussing, but how about the general case? When the 
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angle is more acute, as shown in Figure 9-19, the situation 
changes. Now delta Y is greater than delta X, and we must 
increment Y by one and X by some fractional value. Very 
well — for this case we'll do just that. But wait a minute 
— how many cases are there? 



K X 


= 10,Y = 15 




AY 1 






25-15= I 






10 | 






l_ 


AX = 
15-10=5 


= 15,Y=25 


Figure 


9-19. Second Case of 




Angled Line 





There are actually eight cases, when we consider the size 
of delta X to delta Y, and the direction of the line. They're 
shown in Figure 9-20. Four of these increment X, and four 
increment Y. 

AX AY IAXI:IAYI LINE X INCREMENT Y INCREMENT 



+ 


+ 


+ 


+ 


+ 


- 


+ 


- 


- 


+ 


- 


+ 



-o. 


+1 


AY/AX 


""»• 


AX/AY 


+ 1 


>» 


+ 1 


AY/AX 


s 


AX/AY 


-1 


— 


-1 


AY/AX 


s 


AX/AY 


+ 1 


■»< 


-1 


AY/AX 


\ 


AX/AY 


-1 



NOTES: 

1. ax IS X2 - XI 

2. 4Y IS Y2 - Y1 

3. 14X1 IS ABSOLUTE VALUE 

4. I4YI IS ABSOLUTE VALUE 

5. lAXLIAYI IS 14X1 COMPARED TO I4YI. If +. 14X1 IS LARGER THAN IAYI, IF -. I4YI IS LARGER THAN 14X1 

6. INCREMENTS SHOW WHICH VARIABLE WILL BE STEPPED ONE UNIT AT A TIME. AND WHICH WILL BE FRACTIONALLY 



STEPPED 



Figure 9-20. Line 
Drawing Configurations 



The algorithm for the LINE subroutine goes like this: 

1. Find delta X by subtracting X2-X1. Call this value DX. 

2. Find delta Y by subtracting Y2-Y1. Call this value DY. 
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3. If the absolute value of DX is greater than the 
absolute value of DY, PUT 1*256 in XI (X increment), 
absolute value of DX + l in CT (count), and absolute value 
of DY*256/DX in YI (Y increment). X will vary in steps of 
one in this case. 

4. If the absolute value of DX is less than or equal to the 
absolute value of DY, put 1*256 in YI, absolute value of 
DY + l in CT, and absolute value of DX*256/DY in XL Y will 
vary in steps of one in this case. 

5. If DX is negative, negate XI. 

6. If DY is negative, negate YI. 

7. Increment X and Y from their starting values for a 
number of steps equal to CT. 

This algorithm (with some nuances) is shown in the BASIC 
subroutine of Figure 9-21. It does all of the number 
crunching through step 4 above. You could implement the 
code in assembly language, but my trial effort was about 
120 lines (!). The parameters from the BASIC processing 
are POKEed into locations FF00H through FFOAH for use by 
the assembly-language LINE program that does the 
high-speed line drawing. In this way you have the best of 
both BASIC and assembly language (and I can avoid 
explaining 120 lines of code!) 



10000 DX=X2-X1 

10010 DY=Y2-Y1 

10020 IF (DX=0) AMD (DY=0) THEN XI = : 11 = : CT= 1 : GOTO 10070 

10030 IP ABS(DX)>ABS(DY) THEN XI= 256 : CT= ABS( DX ) + 1 : YI = ABS ( DY»256 /DX ) 

10040 IF ABS(DXK = ABS(DY) THEN YI= 256 : CT= ABS( DY ) + 1 : XI= ABS( DX*256 /DY ) 

10050 IF ABS(DXXXCT-1)»XI/256 THEN XI=XI+1 

10060 IF ABS(DYXXCT-1 )»YI/256 THEN YI=YI+1 

10070 IF DX<0 THEN POKE SHFF09.1 ELSE POKE SHFF09.0 

10080 IF DY<0 THEN POKE SHFF0A.1 ELSE POKE &HFF0A.0 

10090 X=X1«256 

10100 Y=Y1«256 

10110 POKE SHFFOO.X-INKX/256 1*256 

10120 POKE &HFF01 ,INT(X/256 1 

10130 POKE SHFF02.Y-INKY/256 )«256 

1011(0 POKE &HFF03, INKY/256) 

10150 POKE &HFF04 , XI-INK XI/256 j *256 

10160 POKE &HFF05.INKXI/256) 

10170 POKE &HFF06 , YI- INK YI/256 1*256 

10180 POKE 4HFF07 . INKYI/256 ) 

10190 POKE &HFF08.CT 

10200 DEFUSR0=SHFF0B 

10210 A=USH0(01 

10220 RETUHN 



Figure 9-21. Line Routine in 
BASIC 
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The LINE routine is shown in Figure 9-22. It performs 
steps 5 through 7 of the algorithm. LINE calls the SETRST 
subroutine described previously. LINE will draw a typical 
20-point line in about 10 milliseconds, not including the 
BASIC processing portion. It will also draw vertical or 
horizontal lines and points, but not as efficiently as the 
other techniques described. 



FFOO 




00100 




ORG 


0FF00H 














00110 : 


IllfllllflllXfltlllflillilllltll 


lltlllXKCflHIllillllll 








00120 : 


« LINE 


SUBROUTINE. DRAWS A STRAIGHT LINE BETWEEN ANY » 








00130 , 


» TWO GIVEN 


POINTS. OPERATES 


IN 


CONJUNCTION WITH BASIC • 








00110 i 


« DRIVER PROGRAM. ENTER WITH 


BLOCK SETUP AS FOLLOWS: « 








00150 


» BLOCK+0,+1 


: SCALED X VALUE/ 


+2 


+3: SCALED Y VALUE/ » 








00160 


« +1,+ 


5: ABSOLUTE X INCREMENT 


, SCALED/+6 ,+?: ABSOLUTE « 








00170 


« Y INCREMENT, SC ALED/+8 : COUNT/ +9 : 1 IF NEGATE X INC « 








00180 


« ELSE 


0/ + A: 


1 IF NEGATE Y INC ELSE » 








00190 


ft««esis«»«*« 


Mlllll)l»fltlllfIlllllMI«lifflfHlllttflil 








00200 














000B 




00210 E 


LOCK 


DEFS 


1 1 








FFOB 


3A09FF 


00220 I 


INE 


LD 


A,(BL0CK+9) 




GET INCREMENT SENSE 




FFOE 


B7 


00230 




OR 


A 




TEST 




FFOF 


280D 


00210 




JR 


Z.LIN010 




GO IF XINC + 




FF11 


210000 


00250 




LD 


HL,0 




ZERO HL 




FF11 


ED5B01FF 


00260 




LD 


DE,(BLOCK+1 J 




GET XINC 




FF18 


B7 


00270 




OR 


A 




ZERO C 




FF19 


ED52 


00280 




SBC 


HL.DE 




NEGATE 




FF1B 


2201 FF 


00290 




LD 


(BLOCK+D.HL 




STORE - XINC 




FF1E 


3A0AFF 


00300 


.IN010 


LD 


A,(BL0CK+10) 




GET INCREMENT SENSE 




FF21 


B7 


00310 




OR 


A 




TEST 




FF22 


280D 


00320 




JR 


Z.LIN020 




GO IF YINC + 




FF21 


210000 


00330 




LD 


HL,0 




ZERO HL 




FF27 


ED5B06FF 


00310 




LD 


DE, (BLOCK+6) 




GET YINC 




FF2B 


B7 


00350 




OR 


A 




ZERO C 




FF2C 


EB52 


00360 




SBC 


HL.DE 




NEGATE 




FF2E 


2206FF 


00370 




LD 


(BLOCK + 6) ,HL 




STORE - YINC 




FF31 


DD2100FF 


00380 


LIU020 


LD 


IX, BLOCK 






POINT TO BLOCK 




FF35 


DD6601 


00390 




LD 


H , ( I X+ 1 ) 






GET X 




FF38 


DD6E03 


00100 




LD 


L,(IX+3) 






GET Y 




FF3B 


AF 


01 10 




XOR 


A 






FOR SET 




FF3C 


CD5FFF 


00120 




CALL 


SETRST 






SET POINT 




FF3F 


2A00FF 


00130 




LD 


HL, (BLOCK) 






CURRENT X 




FF12 


ED5B01FF 


00110 




LD 


DE, (BLOCK+1 ) 






INCREMENT 




FF16 


19 


00150 




ADD 


HL.DE 






BUMP 




FF17 


2200FF 


00160 




LD 


(BLOCK) ,HL 






STORE 




FF11A 


2A02FF 


00170 




LD 


HL,(BL0CK+2) 






CURRENT Y 




FF1D 


ED5B06FF 


00180 




LD 


DE, (BLOCK+6) 






INCREMENT 




FF51 


19 


00190 




ADD 


HL.DE 






BUMP 




FF52 


2202FF 


00500 




LD 


(BL0CK+2),HL 






STORE 




FF55 


3A08FF 


00510 




LD 


A, (BLOCK+8) 






COUNT 




FF58 


3D 


00520 




DEC 


A 






DECREMENT 




FF59 


3208FF 


00530 




LD 


(BLOCK + 8), A 






SAVE 




FF5C 


20D3 


00510 




JR 


NZ, LIN020 






GO IF MORE 




FF5E 


C9 


00550 




RET 






;RETURN TO BASIC 








00560 


; «»»n»«»««»«»«»»««»«««»»«»»«»»»««»»«««»»««««»«««»«»»»»«» 








00570 


;» SUBROUTINE TO SET OR RESET 


A 


PIXEL GIVEN X (0-127) * 








00580 


i • IN H 


REGISTER AND Y (0-17 1 


IN 


L REGISTER. » 








00590 


;» (A)= 


FOR 


SET, 1 FOR RESET 




* 








00600 


; sft»«»«&sv«9eft*»t**»«*»»«»*»*»*<««**««**»»*e»**»»< 1 ******* 








00610 














FF5F 


F5 


00620 


SETRST 


PUSH 


AF 




;SAVE SET/RESET FLAG 




FF60 


5C 


00630 




LD 


E,H 




;x 




FF61 


7D 


00610 




LD 


A,L 




; Y 




FF62 


CB3B 


00650 




SRL 


E 




:0ET CHAR POSITION (0-63) IN 


E 


FF61t 


1600 


00660 




LD 


D,0 




SET COLS TO 




FF66 


3001 


00670 




JR 


NC.SET10 




GO IF C0Lf=0 




FF6 8 


11 


00680 




INC 


D 




COLS=1 




FF6 9 


06FF 


00690 


SET10 


LD 


B, OFFH 




-1 TO B 




FF6B 


01 


00700 


SET20 


INC 


B 






BUMP QUOTIENT IN B=LINES 
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FF6C 


D603 


0710 


SUB 


3 


FF6E 


F26BFF 


00720 


JP 


P, SET20 


FF71 


C603 


00730 


ADD 


A, 3 


FF7 3 


07 


00710 


RLCA 




FF71 


8a 


00750 


ADD 


A, D 


FF75 


IF 


00760 


LD 


C, A 


FF76 


68 


00770 


LD 


L.B 


FF77 


2600 


007 80 


LD 


H,0 


FF79 


0606 


0790 


LD 


B,6 


FF7B 


29 


00800 SET30 


ADD 


HL.HL 


FF7C 


10FD 


00810 


DJNZ 


SET30 


FF7E 


1600 


00820 


LD 


D.O 


FF80 


19 


00830 


ADD 


HL.DE 


FF81 


1 1003C 


00810 


LD 


DE.3C00H 


FF81 


19 


00850 


ADD 


HL.DE 


FF85 


0600 


00860 


LD 


B,0 ; 


FF87 


F1 


00870 


POP 


AF ; 


FF88 


B7 


00880 


OR 


A ; 


FF89 


200C 


00890 


JR 


NZ, RESET ; 


FF8B 


DD21A3FF 


00900 


LD 


IX. MASK ; 


FF8F 


DD09 


00910 


ADD 


IX, BC ; 


FF91 


7E 


00920 


LD 


A, OIL) : 


FF92 


DDB600 


00930 


OR 


(IX) ; 


FF95 


77 


00910 SET36 


LD 


(HL) , A ; 


FF96 


C9 


00950 


RET 




FF97 


DD21 A9FF 


00960 HESET 


LD 


IX.MASK1 ; 


FF9B 


DD09 


00970 


ADD 


IX, BC ; 


FF9D 


7E 


00980 


LD 


A.(HL) ; 


FF9E 


DDA600 


00990 


AND 


(IX) ; 


FFA1 


18F2 


01000 


JH 


SET36 ; 


FFA3 


81 


01010 MASK 


DEFB 


81 H ; 


FFA1 


82 


01020 


DEFB 


82H 


FFA5 


81 


01030 


DEFB 


81H 


FFA6 


88 


01010 


DEFB 


88H 


FFA7 


90 


01050 


DEFB 


90H 


FFA8 


AO 


01060 


DEFB 


OAOH 


FFA9 


FE 


01070 MASK1 


DEFB 


OFEH 


FFAA 


FD 


01080 


DEFB 


OFDH 


FFAB 


FB 


01090 


DEFB 


OFBH 


FFAC 


F7 


01 100 


DEFB 


0F7H 


FFAD 


EF 


01110 


DEFB 


OEFH 


FFAE 


DF 


01120 


DEFB 


ODFH 


0000 




01130 


END 




OOOOC 


TOTAL ERRORS 







iSUCCESSIVE SUBT FOR /3 

;G0 IF NOT NEGATIVE 
ADD BACK FOR REMAINDER* ROU# 
(R0W#V»2 

(R0W*)"2+C0L*=BIT POS 
SAVE BIT POS IN C 
LINE I 
NOW IN HL 
SHIFT COUNT 

iHULTIPLY LII1E«»61 

;LOOP TIL DONE 
DE HOW HAS CHAR POS 
(LINE* )«61+CHAR POS IN HL 
START OF VIDEO 
(LINE#)«61+CHAR POS+3C00H 
BC NOW HAS BIT POS 
GET SET/RESET FLAG 
TEST FLAG 
GO IF RESET 
START OF MASK TABLE 
POINT TO MASK 
LOAD PIXEL 
SET PIXEL 
STORE IN VIDEO 
RETURN 

RESET MASK TABLE 
POINT TO MASK 
LOAD PIXEL 
RESET PIXEL 
GO TO STORE, RETURN 
MASK TABLE 



Figure 9-22. LINE Routine 
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Chapter Ten 
Cassette Output, Music, and Parallel 

Printers 

We'll be looking at two types of input/output processing in 
this chapter: I/O on the cassette port and parallel printer 
output. We'll also take a look at system I/O in general. 

The TRS-80 reads and writes cassette tape primarily using 
software drivers rather than hardware logic. You can use 
these software drivers in ROM to read and write down to a 
bit at a time from cassette. Because the cassette port is 
easily addressable at an assembly-language level, you can 
also use it to generate "square wave" outputs that can be 
musical tones or other signals. 

System parallel printers are addressed differently than the 
cassette port. We'll see how simple printer drivers may 
be coded. 

Input/Output Programming 

Many programmers are unnecessarily upset by input/ 
output programming. Part of the reason for this is that I/O 
is done automatically in large computer systems; the 
programmer must make special supervisor calls to perform 
I/O through the operating system used on the system. This 
approach is necessary because the system is performing 
many tasks (many "job runs") simultaneously and is 
increasing the throughput by overlapping processing on 
one job with I/O on another. Another reason for the 
mysteries of I/O is some programmers feel that it requires 
an understanding of (ugh!) hardware. 

In the TRS-80, we're operating in a different environment 
than a large multi-programming system (and believe it or 
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not, a much more efficient environment on an individual 
basis). We can perform I/O ourselves without having to go 
through the operating system; of course, the provision is 
also there to have the operating system do our work for us. 
It's user's choice. As far as knowing "hardware," most pro- 
grammers don't realize the simplicity of the logic involved 
in interfacing to most computer peripherals. We'll show 
you how easy it is in this chapter. 

Z-80 and TRS-80 Input/Output 

There are two basic types of I/O in any microcomputer sys- 
tem — I/O mapped I/O and memory -mapped I/O. 

I/O Mapped I/O 

I/O Mapped I/O uses the I/O instructions in the Z-80. 
There are four that we'll talk about here: IN A,(n); IN r,(C); 
OUT (n),A; and OUT (C),r. You can accomplish the same 
thing with all of them: transfer one byte of data between 
an external I/O device and a CPU register. The IN 
instructions read one byte from the external device into a 
CPU register, while the OUT instructions write one byte 
from a CPU register to an external device. 
Hints and Kinks 10-1 



Other I/O. Instructions 

The other I/O instructions are the ' 'block' ' 
I/O instructions. They are somewhat similar in 
action to the block move instructions. Data 
can be transferred between memory and an I/O 
device in a block by setting up a block 
address in HL and a byte count of 1-256 in the 
B register; the C register holds the address 
of the I/O device . 

Like the block moves, the I/O block 
instructions may go forward through the block 
(INIR.OTIR), backward through the block 
(INDR,0TDR), or ' ' semi-automatically ' ' 
(external loop back to INI, IND, OUTI, or 
OUTD). The ''automatic'' I/O block 
instructions cannot be used unless the I/O 
controller has been designed for such a 
transfer. 



212 



The format of these instructions is shown in Figure 10-1. 
All use an I/O address. This is an eight-bit address that is 
contained in the I/O instruction itself (IN A,(n);OUT (n),A) 
or is in the C register (IN r,(C);OUT (C),r). The I/O address 
can be through 255. 



11011011 



IN B, (C) 



OUT (N), A 



OUT (C), R 



11101101 



01 



000 



11010011 



11101101 



01 



001 



HEADS ONE BYTE INTO 
A REGISTER FROM 
DEVICE N 



READS ONE BYTE INTO R 
REGISTER FROM DEVICE 
WHOSE ADDRESS IN C 



WRITES BYTE FROM 
A REGISTER TO DEVICE 
N 



WRITES BYTE FROM R 
REGISTER TO DEVICE 
WHOSE ADDRESS IN C 



Figure 10-1. I/O Instruction 
Formats 



When an I/O instruction is executed, it goes through a 
predefined sequence. The I/O address is first sent out along 
the system address lines A7-A0. Shortly afterwards, data is 
output along the data lines D7-D0 for the OUT, or input 
from the data lines D7-D0 for the IN. 

External I/O devices are designed to expect this sequence. 
If the I/O device senses that an I/O instruction is being 
executed (there is another signal line that performs this 
function), it reads the address lines to determine if it's 
being addressed. If it is, it either reads in the byte of data 
from the data lines or sends back a byte of data to the data 
lines. 
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Hints and Kinks 10-2 

I/O Mapped I/O Signals 

The actual sequence for I/O mapped I/O goes 
like this: The usual I/O cycle is three 
cycles: Tl, T2 , and T3 , The ''port address'' 
is put on address lines A0-A7 during Tl. Next, 
at about T2, the TRS-80 OUT* or IN* signal 
(one or the other) goes to zero. Each is on a 
separate line, IN* signifies that an IN 
instruction is being performed, and OUT* 
denotes an OUT instruction. 

If an input is being done and if an external 
devices 's address is on the address bus, it 
responds by placing a byte of data on the data 
bus lines D7-D0 . The byte is input to the CPU 
register at about T3 , 

If an output is being done and if an external 
device is being addressed, the device 
' 'strobes in' ' the data byte on D7-D0 in T2 or 
T3 , The data was placed on the data lines 
sometime in Tl , 



Since there may be 256 separate port addresses (I/O 
addresses in the I/O instructions), there may be as many 
as 256 separate I/O devices, all looking for their address on 
the address lines so that they can perform their built in 
function of reading or writing one byte of data. In practice, 
there are probably only one or two devices hooked up to 
any microcomputer system. 

Most TRS-80 Model I systems have only two devices. One 
is the cassette read/write logic (address OFFH), and the 
other is the RS-232-C interface board (addresses 0E8H 
through OEBH). Although these are somewhat integrated 
into the TRS-80 system, they are truly external devices 
viewed from the standpoint of the Z-80 microprocessor. 

Model III systems also use cassette and RS-232-C port 
addresses, but use a number of other ports for disk and 
system operations. 
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Memory-Mapped I/O 

The second type of I/O that we can have in the TRS-80 is 
memory-mapped I/O. Here, the external device is still 
looking for an address on the address lines, but all address 
lines A15-A0 are used. In this case, the external device does 
not look for a signal that says "I/O instruction being 
executed" together with its address, but simply looks for 
its address. As 16 address lines are being used, 65536 
separate addresses could be employed. 



Hints and Kinks 10-3 ■ 



Memory-Mapped I/O Signals 

As in I/O mapped I/O, this sequence usually 
takes place in 3 T cycles. First of all, the 
CPU puts the device address onto the address 
bus lines A15-A0 during the Tl cycle. If the 
device is being addressed, it now looks at 
signals WR* and RD* . 

If an input is being done, signal RD* goes low 
(0) during T2 . An external device responds to 
its address and RD* by placing a byte of data 
on data bus line D7— DO . If an output is being 
done, signal WR* goes low during T2. An 
external device responds to a WR* and address 
by ' 'strobing in 1 ' the data on lines D7-D0 . 
The data was placed on these lines by the CPU 
sometime in Tl . 

Note that in this type of addressing, the WR* 
and RD* signals are generated by instructions 
such as LD (HL),A for an output (WR*) and LD 
(nn),A for an input (RD*). The I/O device 
looks identical to a memory location in this 
mode . 



The catch in the above is that some of the addresses are 
also used for memory! In this type of I/O, there must be a 
decision by the system designer on how to divide up the 
64K worth of addresses into memory and I/O addresses. 
This division in the TRS-80 is shown in Figure 10-2, which 
shows the memory mapping for the TRS-80. 
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ADDRESS 
(HEX) 









LEVEL II 

ROM 




3000H 






H000H 


VIDEO MEMORY 




Q000H 


' - " 




C.000H 


, " 

IflplplfefiiP^ 





THIS AREA ALLOCATED 
FOR I/O ADDRESSES 
38MH-3BFFH (MODEL II 
OR USED PARTIALLY FOR 
ROM (MODEL III) 



□ 



FFFFH 



Figure 10-2. TRS-80 Memory 
Mapping For I/O 

Of course, as we know, many of the addresses in the 
TRS-80 are devoted to video memory (addresses 3C00H 
through 3FFFH). In fact, this is very similar to regular RAM 
memory. Other memory-mapped addresses, however, are 
the system line printer (37E8H), and (in the Model I) the 
disk controller chip (37E0H, 37ECH through 37EFH), and 
the cassette latch in the expansion interface (37E4H). 

To address any of these addresses on a read, we simply 
perform any memory reference instruction, such as LD 
A,(37E8H) or LD B,(HL). To address any of the addresses on a 
write, a store is done as in LD (37E8H),A or LD (HD,C. The 
memory reference instruction, of course, transfers one byte 
of data between the external (to the Z-80) I/O device and a 
CPU register. 

Just about all I/O operations in the TRS-80 are performed 
one byte at a time by using either an I/O instruction in I/O 
mapped I/O, or by using a memory reference instruction in 
memory-mapped I/O. (Even disk operations are performed 
one byte at a time.) 
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Hints and Kinks 10-4 

Other Types of I/O 

We haven't talked about several other possible 
types of I/O in the TRS-80 for a good reason - 
they are not used in standard TRS-80 devices. 
However, let's mention them anyway, as the 
provision is there in the TRS-80 as far as bus 
signals . 

The first of these is DMA, direct memory 
access. In this type of I/O, 8-bit I/O 
transfers are made directly to and from memory 
by the I/O device controller, bypassing CPU 
registers. During each transfer, the CPU is 
1 'locked up' ' and the device controller uses 
the bus lines in a ''cycle-stealing' 1 mode. 
This type of I/O is common for very high-speed 
devices where a software loop can not furnish 
the data at high enough rates. 

The second type of I/O is the interrupt-driven 
I/O. This type of I/O is usually used with 
slow-speed devices. Each byte (for example, a 
keypush) generates an interrupt to the CPU, 
which causes an interrupt-processing routine 
to be entered. The interrupt-processing 
routine contains normal I/O instructions to 
read in or write out the data. The advantage 
of this type of I/O is that normal processing 
can be maintained until the interrupt occurs 
without any polling or overhead in testing the 
I/O device for the next byte. 



Parallel Printer Operation 

The system parallel printer uses memory-mapped I/O with 
an address of 37E8H. The expansion interface in the Model 
I or printer logic in the Model III decodes this address 
and passes data either to the printer or from the printer, 
as shown in Figure 10-3. 
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SYSTEM PRINTER 



Figure 10-3. Parallel Printer Logic 

Printers used on the TRS-80 use a somewhat standard 
interfacing specification called the Centronics bus. This 
specification defines the set of lines used to transfer the 
data and the signals for handshaking, timing, and signal 
levels. 

The handshaking logic for parallel printers goes 
something like this. The CPU performs a memory- 
reference read instruction to read a byte of data from the 
printer controller logic. This byte is a status byte, as 
shown in Figure 10-4. 
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Figure 10-4. Printer Status Byte 
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The status byte normally contains several bits indicating 
"fault" conditions for the printer — printer out of paper, 
off-line, etc. It also contains a bit known as a ready bit. 

The ready bit signifies that the printer is ready to accept 
the next byte of data to be printed. In an unbuffered 
printer, the printer is busy (not ready) during the time 
the character is being printed, and the ready bit is not set. 
After the character has been printed, the ready bit is set 
by the printer electronics. This situation is shown in 
Figure 10-5. 



BUSY 



READY 



~L 



PRINT STRING = "TRS-80' 

PHINT "R" PRINT 



r: 



Figure 10-5. Ready/Busy Status 
In a buffered line printer, the printer may receive the 
next byte of data to be printed while the printer is in the 
process of printing. The character is stored in a buffer 
memory within the printer. Of course, if the printer is 
printing at a rate of 100 characters per second and the 
program is outputting characters at rates of 50,000 
characters per second, it doesn't take too long for the 
buffer to become filled up. In this case, the ready bit is 
reset until one or more characters have been read out of 
the buffer and printed. Almost all current line printers are 
of the buffered type. 

Figure 10-6 shows a typical line printer driver program 
from the MORG program of Chapter 14. The status is first 
read from the printer controller logic by a LD A,(37E8H). 
The status bits are ANDed with 0F0H to mask out the bits 
from the other bit positions; they contain ones as they 
connect to nothing for a read from the printer. The other 
four bits are BUSY, OUTPAPER, UNIT SELECT, and FAULT. If 
the result is other than 30H, the printer is busy or has a 
fault condition, and a jump is made back to the read status 
instruction. 
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Other Line Printer Characters 

If the line printer is very complex, there may 
be a variety of ' 'control codes' ' with special 
meanings that can be output. First of all, 
there are carriage returns (ODH) and line 
feeds (OAH) , Most printers also have a ' 'top 
of form, ' ' which advances the paper to the 
next page (OCH) . 

Another common control code is the ' 'BEL' ' 
code (07H) which literally rang a bell on 
early teleprinters; on modern line printers it 
usually sounds an electronic alarm. 

Depending upon the printer, you may have codes 
for such things as underlining, setting 
vertical spacing, and setting horizontal print 
density. 

On character-oriented printers — such as the 
Diablo, Qume, and NEC — you have a whole set 
of special ''escape sequences'' that control 
such things as horizontal and vertical spacing 
in fractions of an inch, vertical and 
horizontal tabs, and ribbon selection. These 
sequences are not single codes but are a 
series of characters, many times started by an 
''escape'' character (1BH). If these printers 
are to be utilized to their fullest advantage, 
the printer software driver must make 
provision for outputting such sequences; this 
may increase the task of writing an 
assembly-language driver by a factor of ten or 
more ! 
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; RETURN 



Figure 10-6. Line Printer Driver 
Program 
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If the line printer is ready, the ASCII character is retrieved 
from the stack and output to address 37E8H by an LD 
instruction. All data output to the printer must be ASCII 
data, except for possible special control codes unique to the 
printer. (A BEL code of 07 would sound an alarm, or a code 
of 29 might select 20 characters per inch spacing, for 
example.) 

Of course, the line printer driver shown above is the 
lowest-level subroutine for communication with a system 
printer. There may be others above it that control message 
output, format lines, and so forth. This simple protocol is 
typical of many peripheral devices such as line printers, 
paper tape readers, and card readers. 

Cassette I/O 

The cassette controller is contained in the CPU logic. 
Like the printer controller, it contains logic to decode its 
address and to transfer data between a CPU register and 
the I/O device. While the printer controller uses memory- 
mapped I/O addressing, however, the cassette logic uses 
I/O mapped I/O via IN and OUT instructions. The cassette 
logic is shown in Figure 10-7. 
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Figure 10-7. Cassette Logic 
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Cassette Output 

When an OUT (0FFH),A or similar instruction is done, the 
four least significant bits in A (or another CPU register) 
are transfered to the cassette latch shown in Figure 10-7 
for the Model I. The latch is really a four-bit memory cell 
that retains the data until rewritten. The logic for the 
Model III is similar, but not identical. 

Bit 3 of the latch (Model I) controls the 32/64 character 
mode for the display. Bit 2 of the latch (Model I) controls 
the cassette relay that would normally be used to turn the 
cassette motor on and off. Bits 1 and (Model I and III) 
generate a signal level to the cassette input for writing on 
cassette. Three signal levels are possible, as shown in 
Figure 10-8. 



"POSITIVE-GOING" 
PULSE 



LEVEL 1 
LEVEL 2 
LEVEL 3 



"STATIC" LEVEL 



"NEGATIVE-GOING" 
PULSE 



LEVEL 1 = XX91 IN CASSETTE LATCH 
LEVEL 2 = XXSO IN CASSETTE LATCH 
LEVEL 3 = XX 18 IN CASSETTE LATCH 

Figure 1@-8. Cassette Output 
Levels 



To write on cassette tape, a series of pulses are generated 
as shown in Figure 10-9. The separation between the 
pulses is 1 millisecond. The width of each pulse is 250 
microseconds, divided into 125 microsecond segments. 
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NOTE: 500 BAUD MODEL l/lll SHOWN 

Figure 10-9. Cassette Pulse Formats 



There are two pulses for every data bit. Each set of two is 
divided into a clocking pulse and a data pulse. There is 
always a clocking pulse. If there is a data pulse at the 1 
millisecond time, a "1" bit is generated. If there is no data 
pulse, a "0" bit is produced, as shown in the figure. 

Prior to the generation of pulses, of course, the cassette 
must have been turned on by a 0000X100 output, which 
turns on the cassette relay; the X represents the current 
state of 32/64 character mode (Model I), which must be 
retained. The positive portion of the cassette is produced 
by outputting a binary 0000X101, and the negative portion 
by a binary 0000X110. The reference level is produced by an 
output of 0000X100. 

The normal sequence for writing to cassette is to turn on 
the motor, write a string of 255 bytes of zeroes (2040 bits 
of zeroes), and then write a sync byte of 0A5H. This really 
amounts to turning on the motor and then writing zeroes 
for 2040*2 milliseconds = 4.08 seconds, following with a 
sync byte. The sync byte is detected in the software read 
cassette routine and marks the start of all data (and the 
end of the zero header). 
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Cassette Input 

The cassette read logic consists of a one-bit read latch and 
comparator logic. The software read cassette routine reads 
one bit from the cassette at a time. This bit is read into bit 
7 by performing an IN A,(0FFH) or similar instruction. If the 
bit is a zero, there is no pulse present from the cassette 
input; if the bit is a one, there is a pulse present. 

The following discussion applies to 500-baud cassette rates 
in the Model I, but is very similar for Model III operations. 

The normal read cassette operation begins with turning 
the cassette motor on. The cassette read latch is cleared by 
an IN (0FFH),A (A may have any data). Next a series of IN 
A,(0FFH) instructions is executed until a one bit is read. 
This is the start of the clocking pulse. Then a delay about 
500 microseconds. This puts the cassette tape past the 
clock pulse. Then the cassette latch is reset by an IN 
(0FFH),A. Now another 850 microseconds delay occurs. 
We're now positioned past where the data pulse should 
have been. If a data bit had been present, the read latch 
would now be set. If there is a one after reading the latch 
by an IN A,(0FFH), the data bit was a one, otherwise the 
data bit was a zero. After this sequence, the entire process 
is repeated for the next data bit. Figure 10-10 shows the 
operation. 
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Figure 10-10. Cassette Read Timing 
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The first data bit to be read will be bit 7 of the 0A5H sync 
byte (or noise). After the entire 8 bits of the sync byte have 
been read and verified, the cassette software driver is 
"synced" to the data and can assemble the bytes of the 
cassette record from the individual reads. 

It's entirely possible to write your own cassette I/O 
routines from the ground up, addressing the cassette write 
and read latches. However, there are ROM calls available 
in the EDTASM manual that you may use to perform the 
next level of byte-oriented operations. The calls are: 

• Define drive and turn on motor 

• Turn off motor 

• Write leader and sync byte 

• Write byte 

Read leader and sync byte 

• Read byte 
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High-Speed Tape Operations 

Since the cassette tape is primarily software 
driven, is it possible for you to speed up the 
cassette data transfer rate? The answer is in 
the qualifier ' ' primarily .' ! It is certainly 
possible to write assembly-language code to 
write and read cassette at 1000 baud or 
higher. However, since these frequencies have 
an entirely different set of electrical 
characteristics and the cassette electronics 
are designed to work well with the standard 
baud rates, a higher-speed cassette driver 
would be a dicey thing at best. Best to invest 
in that disk than in an experimental 19,200 
baud cassette tape driver! 



Define Drive, Motor On, Motor Off 

A CALL to location 212H with the A register containing a 
or 1 selects cassette or 1 and turns on the motor. A CALL 
to location 01F8H deselects the cassette and turns the 
motor off. 
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Eead Cassette 

A CALL to location 0296H looks for the leader of 255 zeroes 
and the sync byte of 0A5H. It returns after a sync byte has 
been read. If no sync byte is read, it "hangs," looking for 
the elusive 0A5H. After this call has been made, a CALL to 
0235H will read in the remaining bytes in the cassette 
record. A byte is returned in the A register. 

Write Cassette 

A CALL to location 0287H writes the leader and sync byte. 
A CALL to location 0264H with a data byte in A writes one 
byte of data. 

The above routines may be used in any fashion to create 
your own tape data formats or to work with existing data 
formats. All tape operations will be at 500 baud (500 data 
bits per second) rates. For example, the size of records is 
normally less than 256 bytes. You may construct your own 
assembly-language routines to block more than one 
logical record into one physical record. 

Figure 10-11 shows an assembly-language routine to write 
and read video display data in 1024-byte records by 
utilizing the ROM calls above. This is a relocatable 
program and is incorporated into the Level II BASIC 
program shown in Figure 10-12. 
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7F1C 


AF 


00310 


XOR 


A 
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CALL 


I12H 


7F20 
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00360 


CALL 


296H 
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LD 


HL.3C00H 
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LD 
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INC 
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LD 
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CP 
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JR 
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JR 
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END 





;SELECT CASSETTE 
iTURN ON 
iREAD LEADER 
;SCREEN START 

;SAVE PNTR 

;READ BYTE 

;GET ADDRESS PNTR 

; STORE BYTE ON SCREEN 

;BUHP PNTR 

;GET MS BYTE 

iTEST FOR 4000H 

;G0 IF NOT END 
;END ACTION 



00000 TOTAL ERRORS 



Figure 10-11. Cassette/Video 
Program 



50 CLEAR 100 

100 'BASIC ROUTINE WITH EMBEDDED VIDEO/CASSETTE PROGRAM 

200 A$=STRING$(52, " » " ) 

300 B=VARPTR(A$) 

400 B=PEEK(B+2)*256+PEEK(B+1 ! 

500 FOR I=B TO B + 51 

600 READ A 

700 IF I>32767 THEN POKE 1-65536. A ELSE POKE I, A 

800 NEXT I 

900 IKPOT "READ(R) OR WRITE ( W )": A$ 

1000 C=B 

1100 IF A$="W" GOTO 1300 

1200 C=C+27 

1300 POKE 16526, C-INTCC/256 1*256 

1400 POKE 16527 , INT(C/256 ) 

1500 INPUT "READY CASSETTE, HIT ENTER";A$ 

1600 X=USR(0) 

1700 GOTO 900 

2000 DATA 243,175,205,18,2,205,135,2,33.0,60,229,126,205,100,2 

2100 DATA 225, 35. 124, 254, 64, 32, 244, 205, 248, 1, 201, 243, 175. 205, 18, 2 

2200 DATA 205,150,2,33.0,60,229,205,53,2,225,119,35.124,254,64 

2300 DATA 32,244,24,227 



Figure 10-12. Cassette/Video 
BASIC Driver 



Cassette Music 

As most of you know, the TRS-80 cassette latch is being 
used to generate musical tones ranging from Morse code to 
four-voice fugues. The music generated is a constant-level, 
square-wave tone produced by toggling the cassette 
output bits on and off. 

In the simplest case, this involves turning on a positive 
pulse by 01 and then turning on a negative pulse by 10' 
bits, as shown in Figure 10-13. The CON subroutine from 
Chapter 14, for example, toggles the two bits by XORing 
the current configuration of the bits with 3, which 
alternates between writing 01 and 10 (see Figure 10-14). 
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Figure 10-13. Cassette Square Wave 
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LD 
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;F0R 1 MS 


34B CDC085 


04630 




CALL 


DELAY 


; DELAY 1 MS 
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CALL 


INPUT 


;GET POSSIBLE CHARACTER 
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04650 




POP 


HL 


;GET COUNT 


352 09 
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ADD 


HL.BC 


;DECREMENT COUNT 


353 38EE 
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JR 


CON010 


;G0 IF NOT -1 


355 09 


04680 




RET 




iRETURN 



Figure 10-14. CON Routine 



The delay between the outputs is accomplished by calling 
the DELAY subroutine, which delays 1 millisecond. As the 
total period of the cycle is 2 milliseconds, a 500 hertz tone 
is produced for the Morse code dots and dashes. A duration 
count in HL is decremented down to zero to generate the 
tone for a given length of time. 
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LD 


A .01 


;bit configuration 


LD 


B »C 


5GET DELAY COUNT 


OUT 


(0FFH) ,A 


5TOGGLE ONE WAY 


DJNZ 


LDOPZ 


;delay 


XOR 


3 


i INVERT BITS 


JP 


LOOP1 


.CONTINUE 



In general, what range of tones can be generated by using 
this method of producing sounds? Producing low tones is 
no problem because we can delay as long as we wish 
between toggling the cassette latch output. (Of course, the 
fidelity of the output on either high- or low-frequency 
tones is another matter.) 

The problem here is in producing high-frequency sounds. 
To do this, we must keep a "tight" loop in the code to 
toggle the cassette latch between positive and negative 
pulses. As we're talking about a general case "tone 
driver," we need some means to vary the period to produce 
different notes. 

About the tightest loop that can be used is: 



L00P1 
L00P2 



This takes a delay count in C and puts it into B for each 
one-half cycle. Either a 01 or 10 is then output to the latch 
at OFFH (the motor bit and mode select will be zeroes). The 
count in B is then decremented down to zero, the bit 
configuration is inverted, and the process is repeated. 

The frequencies that you can produce by this code are easy 
to figure out. The instructions from LOOP 1 through the JP 
L00P1 take 2.3, 6.2, 7.3/4.5, 3.9, and 5.6 micro- 
seconds, respectively. (We took the T cycle times in the 
EDTASM manual and multiplied by .56 to get the times in 
microseconds.) The 7.3/4.5 microsecond time represents 
the DJNZ time for B<>0 and B=0. The total period for any 
count in C, is therefore: 

PERIOD (microseconds) 

= <2.3 + S,2+(CI\IT-i )*7.3+4,5+3,9+5.G)*2 
= 43 + 2*CNT 

The maximum frequency would be for a minimum period 
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when CNT=l, which would be a period of 45 microseconds, 
representing about 22,000 cycles per second (hertz). The 
minimum frequency would be for a CNT of (256) and 
would be a period of 555 microseconds for a frequency of 
1800 hertz. 

There are several problems with this routine. First of all, 
we need more than just a continuous tone; we need some 
way of terminating! That means that we must maintain 
another count for duration. This count is also necessary to 
produce different durations for musical notes, if we want 
to implement a full-fledged music program. 

Secondly, it appears that we need to keep a larger count in 
16 bits for lower frequency notes. The lowest frequency 
here is 1800 hertz, which is much too high. 

There's also another problem, which is not readily obvious. 
The frequency resolution may not be fine enough. The 
difference in frequencies for a CNT of 200 and 201 is about 
10 hertz. This will probably become more pronounced as 
we add more overhead to the loop. 
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Other Tone Parameters 

A full-fledged music synthesizer should 
include some means to control the volume of 
the output for ''envelope generation' 1 or just 
plain dynamics. About the best we can do with 
the cassette output on the TRS-80 is to 
program two levels - one from the 10 level to 
the 01 level (low to high) and one from the 10 
level to the 00 level (low to reference). 

Another parameter that has some interesting 
effects, however, is the ''duty cycle'' of the 
square wave. We've been working with a 
50%-on/50%-off square wave here. However, the 
harmonic content of square waves will vary 
with the proportion of on to off time, and you 
might want to experiment with this parameter 
as an input for the TONE routine (keeping the 
period constant) . 
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All this means is that producing musical tones via the 
cassette port is a compromise (even at best) between range 
of notes and resolution. 

The program in Figure 10-15 is an attempt to produce a 
wide range of musical notes with good resolution by using 
two separate routines within the one subroutine, one for 
high frequencies (HIFREQ) with low overhead and one for 
low frequencies (LOFREQ) with high overhead. 



FF00 




00100 




ORG 


OFFOOH 








00110 


****i 


i «*•»»*« 


HllilnHfllllll 


•••••••••>>ii. •!■. «,*,,, 






00120 


* 




TONE GENERATOR 








00130 


* GENERATES HIGH OH LOW FREQUENCE RANGE OF TOHES. SYM- 






001(0 


* ETHICAL SQUARE HAVE THROUGH CASSETTE OUTPUT 






00150 


» ENTRY: (HL) = 


DURATION IN S CYCLES AT FREQUENCY 






00160 


" 


<BC) = 


FREQUENCY COUNT FROM EXTERNAL TABLE 






00170 


* 


(A)=C 


IF UP TO 300 HERTZ, 1 IF ABOVE 300 HZ 






00180 


»«*«» 


« **** **ti 


IHllHHIlHIHIlllllHlilHlMHillllll 


0002 




00190 I 


UHA 


DEFS 


2 


DURATION POKED BY BASIC 


0002 




00200 f 


REQ 


DEFS 


2 


FREQ CNT POKED BY BASIC 


0001 




00210 F 


LAG 


DEFS 


1 


FLAG POKED BY BASIC 


FF05 


F3 


00215 1 


ONE 


DI 




DISABLE RTC 


FF06 


2A00FF 


00220 




LD 


HL, (OFFOOH) 


GET DURATION 


FF09 


ED1B02FF 00230 




LD 


BC,(0FF02H) 


GET FREQ COUNT 


FF0D 


3A0HFF 


00210 




LD 


A, (0FF01 H) 


GET FLAG 


FF10 


B7 


00250 




OR 


A 


TEST HIGH, LOW 


FF1 1 


2009 


00260 




JR 


NZ.T0N010 


GO IF HIGH 


FF13 


E5 


00270 




PUSH 


HL 


DURATION TO IX 


FF11 


DDE1 


00280 




POP 


IX 




FF16 


C5 


00290 




PUSH 


BC 


FHEQ CNT TO HL 


FF17 


E1 


00300 




POP 


HL 




FF18 


CD22FF 


00310 




CALL 


LOFHEQ 


GENERATE TONE 


FF1B 


C9 


00320 




RET 






FF1C 


0600 


00330 1 


OHO 10 


LD 


B, 


CLEAR B OF BC 


FF1E 


CD16FF 


00310 




CALL 


HIFREQ 


GENERATE TONE 


FF21 


C9 


00350 




RET 










00360 ; 


LOW 


FREQUENCY 


TONE GENERATOR 




FF22 


2241FF 


00370 L 


OFHEQ 


LD 


(FCNT).HL ; 


STORE FREQ CNT( 16) 


FF25 


1 1FFFF 


00380 




LD 


DE.-1 ; 


DECREMENT* 10) 


FF28 


2A11FF 


00390 L 


OOP1 


LD 


HL, (FCNT) 


;GET FREQ CUT! 16) 


FF2B 


3E01 


001)00 




LD 


A, 1 


:HIGH PULSE(7) 


FF2D 


D3FF 


Oil 1 




OUT 


(OFFH) , A 


;TURN ON(11) 


FF2F 


19 


00420 L 


00P2 


ADD 


HL.DE 


i DECREMENT F CHT!11) 


FF30 


DA2FFF 


00130 




JP 


C, LOOP2 


;G0 IF NOT -1(10) 


FF33 


2A14FF 


00110 




LD 


HL.(FCHT) 


iGET FHEQ CNT( (16) 


FF36 


3E02 


015 




LD 


A, 2 


;LOH PULSE(7) 


FF38 


D3FF 


00160 




OUT 


(OFFH) ,A 


; TURN OFF(11) 


FF3A 


19 


00170 L 


00P3 


ADD 


HL.DE 


; DECREMENT F CNT(11) 


FF3B 


DA3AFF 


00180 




JP 


C.LOOP3 


;G0 IF NOT -1(10) 


FF3E 


DD19 


00190 




ADD 


IX, DE 


; DECREMENT DURATI0N(15) 


FF10 


DA28FF 


00500 




JP 


C, LOOP1 


;G0 IF NOT -1(10) 


FF13 


C9 


0051 




RET 




RETURN(IO) 


0002 




00520 F 


CNT 


DEFS 


2 ; 


TEMPORARY STORAOE 






00530 c 


HIGH 


FREQUENCY TONE GENERATOR 




FF16 


1 1FFFF 


00510 H 


IFREQ 


LD 


DE.-1 ; 


DECREHENTf 10) 


FF19 


11 


00550 L 


00P4 


LD 


B,C 


;GET FREQ CNTd ) 


FF4 A 


3E01 


00560 




LD 


A, 1 


;HIGH PULSE(7) 


FF1C 


D3FF 


00570 




OUT 


(OFFH), A 


iTUHN ON(11) 


FF1E 


10FE 


00580 L 


00P5 


DJNZ 


LOOP5 


;GO IF NOT 0(8/1 3) 


FF50 


141 


00590 




LD 


B,C 


:GET FREQ CNT(1 ) 


FF51 


3E02 


0600 




LD 


A, 2 


;L0W PULSE(7) 


FF53 


D3FF 


006 10 




OUT 


(OFFH) ,A 


:TURN OFFOl) 


FF55 


10FE 


00620 L 


00P6 


DJNZ 


LOOP6 


:G0 IF NOT 0(8/13) 


FF57 


19 


00630 




ADD 


HL.DE 


;DECHEMENT DURATION(U) 


FF58 


DA19FF 


00640 




JP 


C.L00P4 


;G0 IF NOT -1(10) 


FF5B 


C9 


00650 




RET 




RETUHN( 10) 


0000 




00660 




END 






00000 


TOTAL 


ERH0HS 











Figure 10-15. Cassette TONE 
Routine 
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Two values are used on entry. HL holds the "duration 
count," while BC holds the "frequency count." The 
frequency count FD represents the number of iterations 
through either LOFREQ or HIFREQ to produce a desired 
frequency. The frequency count FC for any tone less than 
300 Hz. can be determined by 

FC = (l/F-52.45 microsecs)/23.68 microsecs and for any 
tone greater than 300 hz. by 

FC=(1/F-31 microsecs)/14.66 microsecs 

These formulas are found by adding up the instruction 
times in the two routines (T cycle lengths are shown in 
parentheses). 

The duration count DC is simply a count of the number of 
cycles for any frequency for a given duration in seconds. 
(For one second duration, this is F cycles). 

DC=D*F-1 

The - 1 represents the adjustment for the J P C 
termination instead of termination on zero. 

Typical values for F(frequency), D(duration), FC(frequency 
count), and DC(duration count) are shown in Figure 10-16. 



Frequency (Hz) 


Duration (Sees) 


Timing Count 


Duration Count 


100 


.25 


420.053 


24 


300 


■ 15 


225. 26 1 


74 


500 


.15 


134.3II 


124 


700 


.IS 


95.3323 


174 


<?00 


■ ZS 


73.6774 


224 


UOO 


.25 


59.8971 


274 


100 


.5 


420.083 


49 


300 


.5 


225.261 


149 


500 


.5 


13-4.31 1 


249 


700 


.5 


95.3323 


349 


900 


.5 


73.6774 


449 


!IO0 


.5 


59.8971 


54-9 


100 


.75 


420.083 


74 


300 


.75 


225.261 


224 


500 


.75 


134.311 


374 


700 


,75 


95.3323 


524 


900 


.75 


73.6774 


674 


1100 


.75 


59.6971 


624 


100 


1 


420.083 


99 


300 


1 


225.261 


29? 


500 


1 


134.311 


499 


700 


1 


95.3323 


699 


900 


J 


73.6774 


899 


1100 


1 


59.6971 


1099 




Figure 10-16. 


Timing Count Vs, 
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Because these counts would be hard to "number crunch" in 
assembly language, we've provided a BASIC driver to inter- 
face to the TONE routine (see Figure 10-17). The driver 
calculates FC and DC from a given frequency and duration 
and calls TONE with FF00H,1H=DC, FF02H,3H=FC, and 
FF04H=0 for a tone <300 hz. or 1 for a tone >=300 hz. It 
would be relatively easy for you to produce musical note 
frequencies and durations by adding to this driver. 

100 'TEST DRIVER 

200 D=.25 

300 FOR F=20 TO 2000 STEP 10 

100 G0SUB 10000 

500 NEXT F 

600 GOTO 600 

10000 'TONE DRIVER. ENTER WITH F=FREQUENCY DESIRED, D=DURATI0H 

10010 'IN SECONDS DESIRED. 

10020 IF F<300 THEN FC= ( 1 /F-52 . 13E-6 ) /23 . 68E-6 ELSE 

FC=(1/F-31E-6)/14 .66E-6 

10030 DC=D«F-1 

10040 POKE £HFF00,DC-INT(DC/256 )»256 

10050 POKE 4HFF01 ,INT(DC/256) 

10060 POKE 5HFF02,FC-INT(FC/256 )«256 

10070 POKE 4HFF03,INT(FC/256 ) 

10080 IF F<300 THEN POKE 4HFF0t,0 ELSE POKE SHFF04 , 1 

10090 DEFUSR0=SHFF05 

10100 X=USR0(0) 

10110 RETURN 

Figure 10-17. BASIC TONE 
Driver 
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Chapter Eleven 
Disk I/O in Assembly Language 



We're going to look at another type of I/O device in this 
chapter — the floppy disk drive of the TRS-80. We'll first 
examine some of the physical and electrical characteristics 
of the disk, look at TRSDOS file structure, and then look at 
communication with disk data via assembly-language calls 
to TRSDOS. 



Diskette and Disk Characteristics 

A diskette is a circular piece of mylar coated with a 
ferro-magnetic material. As it comes from the 
manufacturer, it's unmagnetized with no data of any type 
on it. There are no inherent tracks or sectors permanently 
embedded in the magnetic medium. 

The manufacturer usually certifies the diskette. This 
certification process involves writing and reading back data 
at high bit densities to verify that there aren't any gaps or 
flaws in the magnetic material that would cause loss of data. 

There are two basic diskette formats, the hard-sectored 
and soft-sectored. The TRS-80 uses a soft-sectored type of 
diskette format. The hard sectored diskette has ten sector 
index holes, while the soft-sectored diskette has one sector 
index hole, as shown in Figure 11-1. 
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SECTOR 
INDEX HOLE 
ACCESS 



PROTECTIVE 
COVERING 



Figure 11-1. Diskette Structure 



The purpose of the sector index hole is to act as a reference 
for the start of sector 0, the first sector of the ten sectors per 
track for the Model I or 18 sectors per track for the Model III. 
Each sector is filled with 256 bytes of data, making a total 
track's worth of data 2560 bytes (4608 bytes for the Model 
III). Each diskette is normally divided into 35 tracks for the 
Model I or 40 tracks for the Model II, numbered through 34 
(39). The entire diskette can therefore hold 2560*35 = 89600 
bytes of data (184320 bytes for the Model III). 

In addition to the data bytes in each sector, there's header 
and trailer data in the sector. This data contains the track 
#, sector number, and checksum for the sector. In addition, 
there is "filler" data preceding and trailing the ten sectors 
worth of data, as shown in Figure 11-2. 
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"HEADER" DATA: 
TRACK, SECTOR ID, 
CRC. FILLER (25 
BYTES TYPICAL) 



Note: Model I 
configuration shown. 



Figure 11-2. Disk Header/Trailer 



All of this data is put on the disk by the formatting 
program. The formatting program is a simple program that 
you use to format the header, trailer, and filler data on the 
diskette in preparation for storing actual data in the data 
portion of each sector. You might visualize the action of the 
formatting program as putting a "skeleton" of the sector 
structure on disk. The formatting program simply stores 256 
bytes of dummy data for the 256-byte data area in each 
sector. 
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Hints and Kinks 11-1 

How is Formatting Done? 

You don't really want to format your own 
disks, do you? All right, here goes .... 

Formatting simply involves positioning the 
disk head to each of the 35 (Model I) or 40 
(Model III) tracks and then issuing a ' 'write 
track' ' command to the disk controller chip. 
The write track essentially tells the 
controller ' 'here comes the data, ' ' The data 
consists of ten sector segments and filler. 
The sector segments contain special characters 
that cause data address ' 'marks, ' ' ID address 
marks, and CRC check bytes to be written. The 
actual sequence is FE (ID address mark 
action), track #, sector #, F7 (CRC action), 
filler, data address mark, dummy user data 
(256 bytes of E5 ) , F7 (CRC action), and 
filler, repeated 10 times. 

The formatter program writes this data out one 
byte at a time until the entire track has been 
written , 



.Disk lirives 

In order to locate a track, each 35- or 40-track disk drive 
steps or positions a read/write head one discrete increment 
for each track, as shown in Figure 11-3. There are no other 
track references that the drive can read to find the proper 
track; it has to step the head precisely for each increment to a 
new track. 



REMOTE , // A XX | Jf™-* 

HEAD | __rf &-& ( \ 1| 1 DISTANCE "STEPPED" 

BY READ/WRITE 
HEAD OF DRIVE 



TRACK 30 

Figure 11-3. Disk Drive Operation 
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To perform this task, each drive has a stepper motor or other 
positioning scheme that positions the head precisely. There 
are three basic movements that each drive can perform: it 
can restore the head to a position over track zero, it can step 
inward one track; or it can step outward one track. The 
software controlling the drive usually does a restore 
operation initially, and then keeps track of where the head is 
as it steps in and out over the various tracks. At any time, 
however, it can always easily find track zero again by 
performing a restore. 

The disk drive motor turns at about 300 revolutions per 
minute (5 revolutions per second). This means that data is 
passing under the read/write head of the drive at about 
2560*5 bytes per second (12,800 bytes per second) for the 
Model I and about 4608*5 bytes per second (23,040 bytes per 
second) for the Model III. Since the data is recorded serially 
along the track, this amounts to a string of 102,400 (184,320) 
bits recorded along each track. (In these figures we're 
ignoring the header, trailer, and filler data, which actually 
increases the data rate by 20% or so.) 



■Hints and Kinks 11-2- 



Disk 1/0 Read/Write Timing 
Considering that the data rate is about 12,800 
bytes per second, that means a byte every 78 
microseconds for the Model I, Since the data 
is being written out a byte at a time in a 
software timing loop, the loop itself must be 
fairly ' 'tight' ' to ensure that it can get 
back with the next byte in time. If you miss 
that 78 microsecond ' 'window, ' ' you end up 
with the dreaded lost data condition. The ball 
game is lost, at least for that sector. A time 
of 78 microseconds represents, say, 15 
instructions, so some efficiency in coding is 
called for here, especially if real-time-clock 
interrupt processing is occurring every 25 
milliseconds or so! (RTC processing adds more 
instructions.) For the Model III, the timing 
constraints are even ' 'tighter' ' - about a 
byte every 43 microseconds. 
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The disk drive is really a very dumb device. The signals 
passing from the disk drive to the expansion interface are 
shown in Figure 11-4. There aren't very many. There are two 
lines for WRITE DATA and READ DATA. Since the disk drive 
reads and writes data serially along the track, data is passed 
a bit at a time in one direction or the other. There's also a line 
that passes a STEP command to the drive; associated with the 
STEP line is a DIRECTION line which determines whether the 
track step will be in or out. 



EXPANSION 
INTERFACE 



/ 



DISK 
CABLE- 



WHITE DATA 



J-UTIT. 



READ DATA JTJVL 



WRITE ENABLE 



DRIVE MTR ENABLE 



WRITE PROTECT 



DISK 

DRIVEiSI 



STATUS 
SIGNALS 



NOT ALL SIGNALS SHOWN 



Figure 11-4. Disk Signals 



WRITE ENABLE must be in force to allow writing data to the 
disk. You use DRIVE MTR ENABLE to turn on the disk motor 
for a read or write and SELECT to select the drive and enable 
the operation. 
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Signals coming back include the READ DATA line, and the 
status signals INDEX (true when index hole passes under a 
sensor), TRACK ZERO (true when the head is over track zero), 
and WRITE PROTECT (true when the write protect diskette 
notch is covered). 



Hints and Kinks 11-3 

Status Signals 

Like other I/O devices, the disk and disk 
controller send back status so that the 
program knows about disk conditions and about 
the busy/read state for reads and writes. The 
status byte for a positioning command such as 
a restore command on the Model I would be 



NOT READY 
WRITE PROJECT 
HEAD ENGAGED 
SEEK ERROR 



7 i 


j 


c 




M 




Z 




2 








?. 




1 












1 












1 























BUSY 
INDEX 
TRACK 
CRC ERROR 



As a fun project, load the following BASIC 
program to test ' 'sector 0' ' (index hole) 
status for a Model I disk drive: 

100 POKE 14304»1 

200 A=PEEK ( 1431G) 

300 IF (A AND 2>-2 PRINT "SECTOR 0" 

400 PRINT A 

500 GOTO 200 



The Disk Controller 

As the disk drive is such a dumb device, intelligence for disk 
drive operations must be incorporated elsewhere. Much of 
the intelligence is in the disk controller chip in the 
expansion interface of the TRS-80 Model I or the disk 
controller logic of the Model III. 

The disk controller chip is a small microprocessor in itself. It 

handles all of the lower-level disk operations such as 
• Converting 8-bit bytes into eight serial bits for writes 
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• Assembling serial data into 8-bit bytes for reads 

• Restores (moving the head to track 0) 

• Stepping the head in or out 

• Seeks (finding a specified track) 

• Reading and writing tracks, including formatting data 

• Reading the "ID field" of a sector header 

In doing all of these operations, the disk controller relieves 
the software from controlling the timing and other 
functions as in the cassette drivers. 

The expansion interface of the Model I contains the disk 
controller chip and some additional circuitry for disk drive 
address decoding. A block diagram of this is shown in 
Figure 11-5. There are two general sets of addresses 
associated with the disk. Both are memory-mapped 
addresses that are 16-bit values. (Memory reference 
instructions are used in place of INs and OUTs.) 



DISK 
DRIVE 
SELECT 
LOGIC 



ADDRESS 
37EIH 



EXPANSION 

INTERFACE 



DISK 
CONTROLLER 

CHIP 



ADDRESS 

ENABLE 

37ECH.37EDH, 

37EEH.37EFN 



OR DISK 
LOGIC 



CPU 
BOARD 



Figure 11-5. Disk Logic 
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One of the four possible disk drives on a TRS-80 Model I 
system is "selected" by loading a register with a 1, 2, 4, or 
8 and performing a write to memory location 37E0H. This 
operation essentially turns the drive motor on for about 
three seconds and enables other operations to take place. 
A typical select of drive would be 

LD A»l 5 FOR DRIVE 1 

LD (37E0H) »A iSELECT DRIVE OoT <r-*>¥&^-z^ 

The remaining addresses are 37ECH, 37EDH, 37EEH, and 
37EFH. 

These addresses are all associated with registers in the 
disk controller chip. The general actions for each address 
for a read or write are 



ADDRESS 


READ ACTION 


WRITE ACTION 


37ECH 


Read status 


Write command 


37EDH 


Read track 


Write track 


37EEH 


Read sector 


Write sector 


37EFH 


Read data 


Write data 



All communications from TRSDOS and other software are 
done with the disk controller chip by issuing a series of 
one-byte commands and by transferring one byte of data 
between a CPU register and the disk controller chip. 

For the Model III, the procedure is very similar, except 
that the "memory-mapped" addresses have been changed 
to I/O ports of OFOH, 0F1H, 0F2H, and 0F3H. 
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Hints and Kinks 11-4 • 



Some Disk Controller Commands 

Commands available to the program for the disk 
controller include eleven separate one-byte 
instructions. These include five commands to 
position the head: Restore puts the head over 
track 0; Seek finds a given track; Step , 
Step-in , and Step-Out all move the head either 
in or out one track. 

Read and Write are used to start the process 
of writing one sector's worth of data. Prior 
to the read or write, the head must have been 
positioned over the proper track, and a sector 
register must have been loaded with the sector 
address. The read or write is followed by the 
transfer of 256 bytes in a software loop that 
looks for a status bit indicating that the 
controller can accept the next data byte. 

Read Address reads the track/sector address 
(not often used) . Read Track reads the entire 
formatted track; Write Track writes (formats) 
a track. Force Interrupt causes a software 
interrupt . 



Unfortunately, a large number of commands can be issued 
to the controller chip with complicated actions and 
responses — far too many to adequately cover in one 
chapter. So we'll give you a typical sequence of operations, 
a flavor of how things are done in disk driver programs 
that make up the lowest level of TRSDOS and other 
programs that read and write data to the disk. Figure 11-6 
shows the disk bootstrap program in Level II ROM. It first 
tests to see whether a disk drive is connected to the 
system, restores the disk head to track 0, and then reads 
in the 256 data bytes of sector 0, track 0. This sector 
contains a bootstrap program (BOOT/SYS) that reads in 
the remainder of TRSDOS. 
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0696 




00050 


ORG 


696H 






0696 


3AEC37 


00100 


LD 


A,(37ECH) 




GET DISK STATUS 


0699 


3C 


001 10 


INC 


A 






069A 


FE02 


00120 


CP 


02 






069C 


DA7500 


00130 


JP 


C.75H 




GO IF NO DISK 


069F 


3E01 


00110 


LD 


A, 1 




FOR DRIVE 1 


06A1 


32E137 


00150 


LD 


(37E1H) ,A 




SELECT DRIVE 1 


06 A1 


21EC37 


00160 


LD 


HL.37ECH 




ADDRESS COMMAND 


06 A7 


11EF37 


00170 


LD 


DE.37EFH 




DATA REGISTER ADDR 


06 AA 


3603 


00180 


LD 


(HL) ,3 




RESTORE COMMAND 


06 AC 


010000 


00190 


LD 


BC.OOOO 




DELAY 61K COUNTS 


06 AF 


CD6000 


00200 


CALL 


0060H 






06B2 


CB16 


00210 


L00P1 BIT 


0,(HL) 




;TEST BUSY 


06 B1 


20FC 


00220 


JR 


NZ.L00P1 




;G0 IF STILL BUSY 


06 B6 


AF 


00230 


XOR 


A 




ZERO A 


06 B7 


32EE37 


00210 


LD 


(37EEH),A 




TO SECTOR REG 


06BA 


100H 2 


00250 


LD 


BC1200H 




MEMORY ADDRESS 


06BD 


3E8C 


00260 


LD 


A.8CH 




READ COMMAND 


06BF 


77 
CB1E 


00270 
00280 


LD 


(HL),A 




READ SECTOR 


06C0 


L00P2 BIT 


1,(HL) 




[TEST DRO. 


06C2 


28 FC 


00290 


JR 


Z.L00P2 




;G0 IF NO DATA AVAIL 


06C1 


1A 


00300 


LD 


A, (DE) 




;GET NEXT DATA BYTE 


06C5 


02 


00310 


LD 


(BO, A 




; TRANSFER DATA 


06C6 


OC 


00320 


INC 


C 




;BUMP BUFFER PNTR 


06C7 


20F7 
C30012 


00330 
00310 


JR 


NZ.L00P2 




;GO IF NOT 256 BYTES 


06C9 


JP 


1200H k 




TRANSFER TO LOADER 


0000 




00350 


END 


\ 






00000 TOTAL 


ERRORS 




\ 


\ 




Note: 


Model 1 Bootstrap 






\ 

LOOP TO READ 258 




Shown. 








BYTES OF TRACK t, 
SECTOR » INTO 42MH 












AREA 





Figure 11-6. Disk Bootstrap 



TRSDOS Disk Organization 

Actually there's no need to write your own disk driver 
routines for the TRS-80. There're a number of TRSDOS 
assembly-language routines that will handle almost all 
disk operations you'd want to perform. These routines 
incorporate not only code to perform rudimentary disk 
operations such as reading a sector and restoring the head 
to track 0, but code to perform disk file manage 
operations on the TRS-80. Disk file manage refers to 
operations to locate, read, and write disk files. We'll 
discuss all of these routines in detail, but first let's look at 
TRSDOS disk organization so that we may better 
understand what is involved. 

TRSDOS disk files are made up of from 1 to 32 granules. A 
granule is five (Model I) or three (Model III) sectors and is 
the minimum amount of space that TRSDOS allocates when 
establishing a new file or adding to an existing file. 
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TRSDOS uses dynamic disc allocation that allocates only 
enough (or slightly more) disk space to hold the current 
number of granules in a file. Deleted files cause the disk 
space used in the file to be released to the pool of disk 
granules (there is a granule allocation table or GAT that 
is essentially a directory of which granules are in use and 
which are in the pool of unused granules). 

As you know from reading your TRSDOS manual, there 
may be up to 48 separate user files on each diskette. A file 
is simply a collection of records which are sets of any type 
of data in some organized fashion. In practice, a file may 
be spread over non-contiguous areas of the disk, but you 
can use the file manage functions of TRSDOS to retrieve all 
records associated with a file by reference to the file 
directory on disk track 17. A typical disk map for the 
Model I is shown in Figure 11-7. 



K0 


DISK BOOT 






1 


"SYS 


B" 




2 






3 


UTILITIES 




4 






5 






6 






7 






8 






9 
10 
11 
12 


FREE FOR 
USER 


NOTE: 
MODEL 1 

CONFIGURATION 
SHOWN. 


13 






14 






15 






16 


'SYS" FILES 




17 
18 
19 

20 
21 


DEDICATED TO SYSTEM 
DIRECTORY 




"SYS" AND 
BASIC FILES 




22 






23 
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24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 



FREE FOR 
USER 



Figure 11-7. Typical Disk 
Map 

A physical record on disk is equivalent to a disk sector. 
At the disk driver level, all disk files are read one sector at 
a time, bringing in 256 bytes of data. However, within a 
physical record there may be one or more logical records. 

A logical record is the actual record used in data storage 
and retrieval by the program. It may be 1 to 255 bytes in 
length. Logical records are blocked into physical records 
(sectors) by the TRSDOS file manage routines. For example, 
if you used 64-byte logical records to hold names and 
phone numbers, four 64-byte records would be packed into 
the sector physical record. One of the main tasks of the 
TESDOS file manage routines is to access the next logical 
record from the proper physical record. 

TRSDOS works with a buffer in memory. A buffer is an 
area of memory set aside to hold the 256 bytes of a 
physical record sector. When we're working in Disk BASIC, 
these buffer areas are preassigned to fixed locations in the 
TRSDOS area; however, we can use our own areas, when 
we're using the TRSDOS routines, as we shall see. 

Device Control Blocks 

Device Control Blocks are "working storage" areas of 
memory dedicated to variables connected with a particular 
I/O driver. Level II BASIC uses several DCBs connected with 
keyboard, video display, and line printer operations; TRSDOS 



247 



uses additional DCBs for disk operations. In both cases the 
location of the DCB is fixed. When we utilize the TRSDOS disk 
file manage calls, however, we can place the DCBs anywhere 
in memory we desire and pass the location of the DCB as a 
parameter. 

We may have as many DCBs as we require. For example, if 
we are merging two files on disk into a third file, we could 
have three DCBs, one for the "old master file," one for the 
"transaction file," and one for the "new master file," as 
shown in Figure 11-8. 



disk <g- 



TRSDOS 

RLE MANAGE 

(I/O) 

ROUTINES 



^ ^ fr 



^ — ^> 



USER 
PROGRAM 



Figure 11-8. DCB Use 



Each DCB has two lives. Before the file operations are started 
(OPENed) and after file operations are terminated (CLOSEd), 
the 32-byte (Model I) or 30-byte (Model III) DCB contains the 
file name in standard TRSDOS format, a carriage return, and 
blanks, as shown in Figure 11-9. During file operations, the 
TRSDOS file manage routines and the user communicate 
(pass parameters) by using variables in the DCB as shown. 
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DCB + 
1 




DCB + 

1 


RESERVED 


2 




2 
3 




3 


BUFFER 


4 


FILENAME 
PADDED 
TO 24 CHAR- 
ACTERS 

WITH 

BLANKS 

(20 H) 


4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 


ADDRESS 


5 


CURRENT DELIM OFFSET 


6 


DRIVE # 


7 


RESERVED 


8 


E0F OFFSET 


9 


LRL 


10 
11 


NRN 


12 
13 


ERN 


14 




15 




15 




16 




16 


RESERVED 


17 




17 




18 




18 
19 




19 




20 




20 




21 




21 




22 




22 

23 
24 
25 




23 
24 


(0DH) 


25 






26 




26 




27 




27 




28 
29 
30 


8 BLANKS 
(20 H) 


28 
29 
30 




31 




31 




49 


(MODEL III) 


49 


(MODEL III) j 




BEFORE 


AFTER OPEN 




OPEN AND 


AND BEFORE 




AFTER CLOSE 


CLOSE 




Figure 11-9. 


DCB Format 



During the file operations, the DCB bytes are used to hold 
variables. The variables are put into the DCB by the TRSDOS 
routines but may be examined by your assembly-language 
code. Some of the variables are initialized from 
user-supplied data, such as the buffer address. 

Bytes + 3 and 4 hold the buffer address for disk reads and 
writes. The buffer may be anywhere in memory that's 
compatible with the configuration; without Disk BASIC, this 
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means anywhere above 6FFFH (Model I) or 6000H (Model 
III). If Disk BASIC is being used, follow the same rules about 
assembly-language memory areas as you normally would 
(see Chapter 4). 

Byte + 5 holds a buffer displacement (or offset) of 1 to 255 to 
the end of the current record. In other words, it's an index to 
the last byte of the current record. If, for example, you were 
processing the second 64-byte logical record of a sector, this 
byte would contain 127. During normal processing, you 
would not employ this variable. 

Byte + 6 holds the file drive number of the disk drive being 
used in the operation. Valid numbers are through 3. This 
constant is stored by TRSDOS from the file name of the DCB. 

Byte + 8 holds the buffer displacement (offset) of the last 
delimiter of the last physical record. In other words, when 
the last sector has been read in, this byte contains an index of 
1 to 255 that points to the last byte of the file. Don't use this 
variable during normal processing. 

Byte + 9 holds the LRL, or logical record length. This 
variable may be 1 to 255 and is put in by TRSDOS from 
user-supplied data. If the LRL is 0, TRSDOS will assume the 
user is blocking his own records and will not find logical 
records for him (more about that later). This variable is 
constant for the entire file. 

Bytes +10 and +11 hold the NRN or next record number in 
standard 16-bit format (Is byte followed by ms byte). This 
variable is set to 000H by TRSDOS after the file has been found 
initially (OPENed) or created (INITialized). It is incremented 
by one by TRSDOS after each read for sequential files, or you 
may change it for random files. 

Bytes + 12 and +13 contain the ending record number of the 
current file in standard 16-bit format. This represents the 
last logical record number of the file. 

Byte +0, +1, +2, +3, +14, +15, +16, +17, and + 18 are 
"reserved," which is a polite way of saying, "Don't tread on 
me!" They should not be altered by the user. 

250 



TRSDOS I/O Calls 

Now that we know how the DCB is set up, let's look at the 
sequence and setup for TRSDOS I/O calls. There is an 
excellent write-up of the calls in the TRSDOS/Disk BASIC 
Reference Manual, so we won't repeat the formats here. 
There are eight calls for the Model I and seventeen calls for 
the Model III. We'll consider the "subset" of eight Model I 
calls here: 

Call Action 

I N I T Initialize a new file 

OPEN "Open" an existing file 

POSN Positions a file to read or write a random 

record 

READ Reads one logical record from disk or buffer 

WRITE Writes one logical record into disk or buffer 

VERF Verifies a physical record 

CLOSE "Closes" an opened file 

KILL Closes a file and deletes it from directory 

In general, all of these calls are made by CALLing a TRSDOS 
routine in the 44XXH area. In all calls, the DE register holds a 
pointer to the first byte of the DCB. HL and B or BC may also 
hold a parameter depending upon the call type. For all calls, 
after the call is made, a successful action returns with the Z 
flag set. If the Z flag is not set on return, an error has 
occurred and the A register contains an error code. Error 
codes for TRSDOS I/O calls, along with probable causes, are 
shown in the TRSDOS/Disk BASIC Reference Manual. 

Reading an Existing I/O File 

The normal sequence to read an existing file is this: 

1. Put the file name in standard format into the DCB. 

2. Make an OPEN call. This causes TRSDOS to search the 
directory and find the file. 

3. If the file is a sequential file, perform a series of READs 
of the next logical record until the last record (ERN or 
ending record number) has been processed. If the file is 
a random file, perform the READs after a POSN call for 
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each READ. The POSN uses the desired NRN (next record 
number) in the DCB to find the required logical record. 
4. CLOSE the file. 

To see how this works in a simple case, enter the BASIC 
program shown in Figure 11-10. Save the program on disk 
by performing an ASCII save: 

SAME "TEST" »A 



100 'THIS IS LINE 1...., 

200 'THIS IS LINE 2 

300 'THIS IS LINE 3 

400 'THIS IS LIME 4 

500 'THIS IS LINE 5 

600 'THIS IS LINE 6 

Figure 11-10 . BASIC ASCII 
Test File 



This will write the file in ASCII format so that we can use the 
program in Figure 11-11 to read it in a record at a time and 
list it on the screen. 



8000 




00100 




ORG 


8000H 




3C00 




001 10 


BUFFER 


EQU 


3C00H 








00120 


; SAMPLE PROGRAM TO READ EXISTING FILE 






00130 














00140 


; FIRST 


OPEN THE FILE 




8000 


21003C 


00150 


READF 


LD 


HL, BUFFER 


;BUFFER LOCATION IN HL 


8003 


1 13B80 


00160 




LD 


DE.DCB1 


;DCB LOCATION 


8006 


0600 


00170 




LD 


B. 


;READ ONE SECTOR 


8008 


CD2444 


001 80 




CALL 


4424H 


;MAKE OPEN CALL 


800B 


2808 


00190 




JR 


Z, REA010 


;G0 IF OK 


800D 


F680 


00200 


REA005 


OR 


80H 


i SETUP FOR ERROR HSG 


800F 


CD0944 


00210 




CALL 


4409H 


; DISPLAY ERROR MESSAGE 


8012 


CD2D40 


00220 




CALL 


402DH 


;REB00T 






00230 


; NOW READ AND 


DISPLAY 




8015 


1 13B80 


00240 


REA010 


LD 


DE,DCB1 


;DCB LOCATION 


8018 


CD3644 


00250 




CALL 


4436H 


iREAD RECORD 


80 1E 


20F0 


00260 




JR 


NZ.REA005 


;G0 IF ERROR 


S01D 


2A3E80 


00270 




LD 


HL,(DCB1+3) 


;GET BUFFER ADDRESS 


8020 


1 10001 


00280 




LD 


DE.256 


; INCREMENT 


8023 


19 


00290 




ADD 


HL.DE 


;BUMP TO NEXT SCREEN SECTION 


8024 


223E80 


00300 




LD 


(DCB1+3) .HL 


;ST0RE FOR NEXT READ 


8027 


DD213B80 


00310 




LD 


IX.DCB1 


;DCB ADDRESS 


802B 


DD7E0A 


00320 




LD 


A, (IX+10) 


;GET NRN 


802E 


DDBEOC 


00330 




CP 


(IX+12) 


; COMPARE TO LRU 


8031 


20E2 


00340 




JR 


NZ.REA010 


;G0 IF ERROR 


8033 


1 13B80 


00350 




LD 


DE.DCB1 


;DCB LOCATION 


8036 


CD2844 


00360 




CALL 


4428H 


; CLOSE FILE 


8039 


18FE 


00370 


REA020 


JR 


REA020 


;JUMP HERE ON END 


803B 


54 


00380 


DCB1 


DEFH 


'TEST 






45 53 54 


20 20 


20 20 20 








20 20 20 


20 20 


20 20 20 








20 20 20 


20 20 


20 








8052 


20 

20 20 20 


00390 
20 20 


20 20 


DEFH 






0000 




00400 




END 






00000 TOTAL ERRORS 











Figure 11-11. Read Test File 
Program 
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The program in Figure 11-11 is a simple read of an existing 
disk file. We did some things in it that are a little dangerous 
(like incrementing 256 bytes each time through the loop for 
the screen address and modifying the buffer address in the 
DCB), so try it only with the TEST file from Figure 11-10. 

The DCB for the read is DCBl. Before we OPEN the file, the DCB 
contains TEST padded out to 23 characters with blanks, a 
carriage return, and eight terminating blanks. This cor- 
responds to the DCB format required by the TRSDOS calls. We 
OPENed the TEST file by CALLing 4424H with the buffer 
address in HL, the DCB address in DE, and the logical record 
length in B. The logical record length in this case is 0, 
signifying that a logical record corresponds to a physical 
record, or sector. 

If an OPEN error had occurred, Z would not be set on return, 
and we would have gone to the special "display TRSDOS error 
message" routine at 4409H and then rebooted. 



Hints and Kinks 11-5 

Error Code Routine 

The error code routine is another TRSDOS call 
that converts the error code returned in the A 
register to a description message. The message 
is then displayed. It makes sense to use it, 
rather than printing out a nebulous ERROR 
178G, SUB A-S DURING HIGHEST HIGH TIDE. 



After a successful open, the DCB contains variable data 
placed in it by the TRSDOS OPEN routine. The DCB appears as 
shown in Figure 11-12. Note that at this time TRSDOS knows 
the length of the TEST file and puts a 0002H in DCB + 12, + 13 
(ERN or end record number). It has also initialized the NRN 
(next record number) to 0000H in preparation for a READ or 
WRITE. 
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DCB + 






1 


SISlllIiSsWilHSffllSlII 




2 






3 


0OH 




4 


3CH 




5 


00H 


6 


00H 


7 




8 


86H 


9 


00H 


10 


00H 




11 


00H 




12 


02H 




13 


00H 




14 






15 






16 






17 






18 







BUFFER ADDRESS = 3C00H 



OFFSET 
DRIVE # 



EOF OFFSET 
LRL = (2561 



NRN = 0OB0H 



ERN = 0O82H 



49 I 



(MODEL III) 






Figure 11-12. DCB After 
OPEN 



The next set of code makes a call to READ a record. If the 
logical record length were not (256 bytes), we would specify 
a "user record" area in HL. The READ call would then transfer 
the next logical record from the buffer into the user record 
area. This might involve a new disk read of the next sector, 
or would simply involve transferring the next logical record 
from the buffer. 

Since we're working with logical records equal to physical 
records (sectors), however, we did not pass anything in HL. 

After a successful READ, the DCB appears as shown in Figure 
11-13. The NRN has been incremented to 1, and the data from 
the sector appears on the screen (buffer). The buffer location 
is now picked up from DCB + 3, + 4 and incremented by 256 to 
point to the next screen location. (Don't try this for more 
than four sectors!) 
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DCB + 




1 




2 




3 

4 


00H 
3CH 


5 


00H 


6 


00H 


7 




8 


86 H 


9 


00H 


10 
11 


01 H 
00H 


12 
13 


02H 
00H 


14 




15 




16 




17 




18 






1 



NRN = B0»1H 



ERN = 9002H 



49 I 



(MODEL III) 



Figure 11-13. DCB After 
READ 



Now we come to an important portion of code. The current 
record number is picked up from DCB + 10 and compared to 
the ending record number in DCB + 12. If they are not equal, 
another READ is done. If they are equal, you perform a CLOSE 
file by CALLing TRSDOS CLOSE at 4428H with DE containing 
the DCB address. For the TEST file, we make two passes 
through the read portion of the code and then CLOSE the file 
and loop at REA020. 

This is in essence how a read of any existing sequential file 
can be accomplished. Many Radio Shack disk files have 
logical record lengths of 256 bytes (look at any DIR display), 
so the procedure for processing any existing BASIC files 
would be very similar to the above code. 
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Creating a New File and Reading It Back 

Now that we've gotten our feet wet with disk I/O, let's try a 
plunge into deep water with a write of a new file and a 
following read. We'll use logical record lengths other than 
256. The program shown in Figure 11-14 takes the contents 
of the screen and opens a new file called SCREEN. SCREEN has 
logical record length equal to the size of a screen line (64 
bytes). There'll be 16 logical records in 4 physical records for 
the SCREEN file. After the file is created it can be read back 
and displayed by the second part of the program. 

The program is divided into three parts — initializing a new 
file and writing it, clearing the screen, and reading the file 
back in. 

Initializing 

The first part calls INIT to create a new file. A 256-byte buffer 
is specified in HL, and the usual DCB is specified in DE. The 
DCB in this case has the name "SCREEN". A logical record 
length of 64 is specified in B. The code at WRT005 is an error 
routine to display any disk error on the screen. 

After a successful INIT, the character string in the DCB is 
replaced with the date shown in Figure 11-15. Note that the 
NRC (next record number) is initialized to 0000H for the INIT, 
just as it was for the OPEN. 
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8000 


00100 


ORG 


8000H 






00110 ; SAMPLE PROGRAM TO WRITE SCREEN 


TO DISC AND READ IT BAC 




00120 ; WRITE SCREEN 






8000 217280 


00130 HRTREA 


LB 


HL, BUFFER 


BUFFER LOCATION 


8003 117281 


00140 


LD 


DE, WDCB 


DCB LOCATION 


8006 0640 


00150 


LD 


B,64 


64 BYTES PER LOG RECORD 


8008 CD2044 


00160 


CALL 


4420H 


CREATE A NEW FILE 


800B 2808 


00170 


JR 


Z, WRT010 


GO IF OK 


800D F680 


00180 WRT005 


OR 


80H 


SETUP FOR ERROR MSG 


800F CD0944 


00190 


CALL 


4409H 


WRITE ERROR MSG 


8012 C32D1I0 


00200 


JP 


402DH 


REBOOT 


8015 21C03B 


00210 WRT01C 


LD 


HL.3COOH-64 


SCREEN STAHT-256 


8018 E5 


00220 


PUSH 


HL 


SAVE ADDRESS 


8019 El 


00230 WRT020 


POP 


HL 


;GET LINE f 


801A 1111000 


00240 


LD 


DE.64 


; INCREMENT 


801D 19 


00250 


ADD 


HL.DE 


; POINT TO NEXT LINE 


801E 7C 


0026 


LD 


A, H 


;GET MS BYTE 


801F FE40 


00270 


CP 


40H 


(TEST FOR LAST LINE 


8021 280B 


00280 


JR 


Z, WRT030 


;G0 IF DONE 


8023 E5 


00290 


PUSH 


HL 


:SAVE UHEC ADDRESS 


80211 117281 


00300 


LD 


DE.WDCB 


;WRITE DCB LOCATION 


8027 CD3944 


00310 


CALL 


4439H 


;WRITE UREC 


802A 20E1 


00320 


JR 


HZ.WRT005 


;G0 IF ERROR 


802C 18EB 


00330 


JR 


WRT020 


;CONTINUE 


802E 117281 


00340 WRT030 


LD 


DE.WDCB j 


DCB LOCATION 


8031 CD28U4 


00350 


CALL 


4428H ; 


CLOSE FILE 


803* 20D7 


00360 

00370 ; CLEAR 


JR 

SCREEN 


NZ.WRT005 : 


GO IF ERROR 


8036 21003C 


00380 


LD 


HL.3C00H ; 


SCREEN START 


8039 3E20 


00390 WRT04 


LD 


A, ' ' 


;BLANK 


803B 77 


001100 


LD 


(HL),A 


:STORE BLANK 


803C 23 


001! 10 


INC 


HL 


;BUMP PNTR 


803D 7C 


00H20 


LD 


A,H 


;GET MS BYTE 


803E FEllO 


00430 


CP 


40H 


;TEST FOR END 


8040 20F7 


004 4 


JR 


HZ, WRT04 


;G0 IF NOT END 




004 50 ; ROW READ BACK 


FILE 




80112 217280 


00460 


LD 


HL, BUFFER ; 


BUFFER LOCATION 


8045 117281 


00470 


LD 


DE.WDCB ; 


DCB LOCATION 


801)8 06110 


00480 


LD 


B,64 ; 


54 BYTES PER LOG RECORD 


804A CD2l|lllt 


004 90 


CALL 


4424H ; 


OPEN SCREEN FILE 


804E 20BE 


00500 


JR 


NZ.WRT005 ; 


30 IF ERROR 


804F 21C03B 


00510 WRT050 


LD 


HL.3C00H-64 ; 


SCREEN START-256 


8052 E5 


00520 


PUSH 


HL ; 


SAVE ADDRESS 


8053 E1 


00530 WRT060 


POP 


HL 


;GET LINE 


8051 1111000 


00540 


LD 


DE.64 


; INCREMENT 


8057 19 


00550 


ADD 


HL.DE 


; POINT TO NEXT LINE 


8058 7C 


00560 


LD 


A,H 


•;GET MS BYTE 


8059 FEUO 


00570 


CP 


40H 


;TEST FOR LAST LINE 


805B 280B 


00580 


JR 


Z, WRT070 


:G0 IF DONE 


805D E5 


00590 


PUSH 


HL 


;SAVE UREC ADDRESS 


805E 117281 


00600 


LD 


DE.WDCB 


;DCB LOCATION 


8061 CD3644 


06 10 


CALL 


4436H 


;READ UREC 


8061 20A7 


00620 


JR 


NZ.WRT005 


;G0 IF ERROR 


8066 18EB 


00630 


JR 


WHT060 


:CONTINUE 


8068 117281 


00640 WRT070 


LD 


DE.WDCB ;DCB ADDRESS 


806B CD2844 


00650 


CALL 


4428H ;( 


LOSE FILE 


806E 209D 


00660 


JR 


NZ.WRT005 jC 


IF ERROR 


8070 18FE 


00670 WRT080 


JR 


WRT080 ;L 


OOP HERE 


0100 


00680 BUFFER 


DEFS 


256 




8172 53 


006 90 WDCB 


DEFH 


'SCREEN 


. 


13 52 115 


45 4E 20 20 20 






20 20 20 


20 20 20 20 20 






20 20 20 


20 20 20 








8189 OD 


00700 


DEFB 


ODH 




818A 20 


00710 


DEFM 


! 1 




20 20 20 


20 20 20 20 








0000 


00720 


END 






00000 TOTAL ERRORS 









Figure 11-14. SCREEN Program 
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DCB + 
1 
2 






3 

4 


72 H 
80H 


> BUFFER ADDRESS = S072H 


5 


00H 


OFFSET 


6 


00H 


DRIVE # 


7 






8 


00H 


EOF OFFSET 


9 


40H 


LRL = 64 


10 
11 


00H 
00H 


NRN = BOOTH 


12 
13 


04H 
00H 


ERN = 00B4H 


14 
15 
16 
17 
18 








I 

! (MODEL III) 


I 
I 



49, 



Figure 11-15. DCB After 
INIT 



Writing 

Now a series of disk writes is done. Each write specifies a 
UREC (user record area) in HL. This would normally be RAM 
memory, but in this case we're using the video screen as a 
user buffer. The user buffer must be the same length as the 
logical record length or greater. In fact each new call to 
WRITE uses the next screen line as the UREC. Each write 
causes 64 bytes to be moved from a screen line into the buffer 
area. After each fourth move, a disk write of the physical 
record (sector) is automatically performed. Typical DCB 
contents are shown in Figure 11-16. 
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DCB + 




1 




2 




3 


72 H 


4 


80H 


5 


40H 


6 


00H 


7 




8 


40H 


9 


40H 


10 


00H 


11 


00H 


12 


04H 


13 


00H 


14 




15 




16 




17 




18 









EOF OFFSET (Reflects Write ot 

First Logical Record) 



NRN=««B»H 



ERN = 0M4H 



Note: After First WRITE 



I (MODEL III) I 

49 | ' I 



Figure 11-16. DCB After 
WRITE 



Clearing 

After 16 writes of the 16 screen lines, a call is made to CLOSE 
to close the SCREEN file. The CLOSE is especially important 
on a write as there may be logical records in the buffer that 
have not yet been written to disk. The CLOSE in this case 
flushes the buffer. 

The screen is cleared with the next bit of code. 

Now an OPEN is done with the same DCB used as in the INIT 
and WRITE. Note that the CLOSE restored the character data 
in the DCB, and that we can perform the OPEN without 
having to reinitialize the DCB with the file name. The OPEN 
specifies a logical record length of 64. In fact, we must know 
beforehand what the LRL will be in reading back a file. There 
is no mechanism for obtaining this from the TRSDOS calls. 
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Reading The File Back 

After a successful OPEN, the NRN (next record number) in the 
DCB is set to 0000H in preparation for the READ (or WRITE — 
the TRSDOS routines don't know which will follow). A series 
of READs is then done in much the same fashion as the 
WRITES. Each read specifies a UREC (user record area) in HL 
which is a video memory line. 

After 16 reads, a CLOSE is done to terminate the read action. 
Note that in this case we knew how long the file was and 
simply read in 16 logical records. This is not very good 
programming practice with files; we really should have 
worked with the ERN (ending record number) and NRN (next 
record number) in conjunction with a discrete count of 
records in case there had been some programming or logic 
error in creating a file that had fewer records than expected. 
We hope you'll forgive us in this example! 

The program will cause the following actions over several 
seconds: The screen contents (a DEBUG display is good) are 
written out to disk. The screen is cleared and filled with the 
same data from the SCREEN file. There are four distinct reads 
as each sector is read in, with four blocks of four lines being 
output rapidly to the screen after each read. 

Killing a File 

The KILL call is very similar to the CLOSE, except that it 
deletes the file name from the directory and releases the disk 
space used for the file to the common pool of granules. The 
action of the KILL can be seen by substituting a CALL 442CH in 
place of the CALL 4428H near WRT070 in Figure 1 1-14. Do a DIR 
command in TRSDOS after a CLOSE and after a KILL, and you 
will observe the KILL action. 

We did not verify the physical records as we were writing 
them out in Figure 11-14. You have a choice of writing out 
each physical record without reading it back in for com- 
parison (a "normal" WRITE) or writing out a record and 
reading it back in for comparison after each sector write. In 
my opinion, you should always verify. I'm assuming that all 
data being written out to disk is important to you. Although 
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the VERIFY takes slightly longer because a second disk 
operation must be performed to read in the sector for 
comparison, it's just good programming practice to 
double-check. 

Change the CALL 4439H after WRT020 to CALL 443CH to 
perform the VERIFY write. You might want to compare the 
time for both a WRITE sequence and a VERIFY sequence. 
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How Many Disk Errors Will There Be? 

(What is Truth? What is Beauty?) The floppy 
disk is an extremely reliable device for an 
electro-mechanical peripheral. If you choose 
not to VERIFY your writes, you'll probably not 
have an error in a diskette full of data. 
However, the overhead really is not that great 
when you consider the high data rates of the 
disk as compared to cassette operation .... 



Using POSN 

We created a sequential file in the code of Figure 11-14 by 
the process of writing a series of logical records in sequence. 
However, it's just as easy to work with random records. 

In the case of a sequential file, the TRSDOS READ and WRITE 
routines keep pointers to the next logical record in the buffer 
in the DCB, along with incrementing the NRN (next record 
number). If we are to work with random records of a file, we 
must aid TRSDOS in locating the physical records by using 
the POSN call. 

The POSN call is used to specify a logical record number in 
the BC register. TRSDOS then finds the proper logical record 
by either resetting the DCB pointers (if the logical record is in 
the current buffer) or reads in the sector containing the 
logical record and positions the pointers. This intermediate 
operation is necessary because there is a good chance that 
the random logical record is not in the current buffer. 
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Hints and Kinks 11-7 — 

Adding to a File 

The POSN command is used to find the last 
record of an existing file so that additional 
records may be appended. To do this, setup the 
BC register pair with a record number 
corresponding to ERN (ending record number) + 
1. The POSN will automatically find the ' 'end 
of file. ' ' You can then do normal WRITES if 
you are adding to a sequential file. 



Figure 11-17 shows the use of POSN in reading the first and 
sixteenth records back from the SCREEN file. The code here 
should be used after the SCREEN file has been created by the 
program shown in Figure 11-14. Two READS are done after 
an OPEN. Each READ is preceded by a POSN call. The first 
POSN specifies logical record number 7, while the second call 
specifies logical record number 15. 

There are many subtleties involved in working with disk 
files, but possibly this brief introduction has been helpful in 
getting you started. Try experimenting with using the disk 
calls as described in the TRSDOS manual. The TRSDOS I/O 
calls may be used to create some powerful assembly- 
language programs that use disk a lot more efficiently than 
BASIC code. 
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Figure 11-17. Use of POSN 
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SECTION III 

Larger Assembly-Language 
Projects 



Chapter Twelve 

Assembly-Language Design, Coding, 

and Debugging 

In this chapter, we'll follow a typical assembly-language 
programming project from beginning to end. It'll be a 
"medium-sized" project, one that might well take a pro- 
fessional programmer a month or more to complete in all 
phases. We'll describe the trials and tribulations of that 
programmer and illustrate the steps required in any large 
assembly-language job. (The punch line of this chapter: 
"For you see, my friends, that professional programmer was 
ME!") 

This is a story about Cal Coder, a programmer/analyst at 
GIGO Software, Inc. GIGO is one of the smaller companies 
producing software packages for the Radio Shack TRS-80 
microcomputers. 

The Inception Phase 

Cal had just walked into his office at GIGO when his phone 
rang. "Cal, this is Paul .... Can you drop in for a second? 
I think we might have something you'll be interested in." 

Having served in the Sea Scouts, Cal knew a direct order 
couched in polite terms. He started toward his boss's office. 

After the usual small talk, Paul explained, "The guys in 
Marketing have come up with this idea about a new 
program for the TRS-80 — the ads start tomorrow, and 
we've already sold a hundred copies. Can you get right on 
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it? Here're the notes on it," he said, handing Cal a 
matchbook cover with an ad for "Earn Big Money in Your 
Spare Time Programming" on one side and several 
scribbled notes on the other. 

Looking over the notes, Cal saw that there was a need for 
a Morse Code Generator program that would act as a 
Morse code instructor or playback prerecorded Morse code 
messages. Marketing had done some analysis in Butte, 
Montana that indicated potential sales of hundreds of 
copies. It was up to Cal to come up with a specification to 
further define the project. 



Research 

"Do you know anything about Morse code?" Cal asked Ted, 
his officemate and fellow-programmer. 

"Is it anything like a Hamming code?" Ted replied, 
puzzled. 

Hints and Kinks 12-1 

Hamming Code 



Ted was making a pun at Cal ' s expense. A 
Hamming code is a special code frequently used 
in telemetry, but not often used in computer 
processing, Missing bits in data can be 
regenerated by analyzing the remaining bits. 
Obviously, the overall data transmission rate 
is reduced by inclusion of data bits for 
reconstruction , 

Few enough bits are ' 'dropped' ' in computers 
to make a code such as this unnecessary in 
normal applications. Parity bits or other 
check bits do provide some verification of 
data, which is usually sufficient. 
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"Well, hams use it, but I don't think so," Cal replied. "I 
guess I'll have to do some research on it before I write that 
spec for the Morse Code Generator I'm working on." 

"Why change your approach now?" Ted asked with a leer. 
Cal threw a carton of C90 cassettes at him. 

Later, Cal had dug up most of what he needed to know 
about Morse code. It was basically a series of long and 
short pulses representing the letters of the alphabet, 
digits, punctuation marks, and some special characters. 
The number of pulses varied. A frequently used letter like 
"e" consisted of one short pulse, called a "dot" or "dit." A 
"t" consisted of one long pulse called a "dash" or "dah." 
Less frequently used letters, digits, and punctuation 
marks consisted of longer combinations of dots and dashes. 
A "p", for example, was represented by "dot dash dash 
dot," while a "5" was "dot dot dot dot dot." 

Cal also located the specifications on the standard lengths 
for dots and dashes and on the spacing. A dot was one unit 
long, while a dash was three units long. The space 
between dots or dashes was one unit long, the space 
between characters was three units, and the space 
between words was five units long. 

Cal verified his findings with some amateur radio friends 
and got more data. He supplemented this research with 
some articles in byte, 80-Microcomputing, and other 
computer magazines, and after several days had done 
enough research to feel he knew more than enough to 
write the spec. 
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The Preliminary Specification 

The spec he produced is shown in Figure 12-1. It's a 
preliminary operational specification that does not show 
anything about the actual implementation of the program. 
As a matter of fact, in looking over the spec, we might ask 
ourselves whether it is possible to produce such a program. 
Certainly we know the TRS-80 can produce messages on 
the screen, can generate audio tones out of the cassette 
output, and read character strings from the keyboard. But 
can it generate Morse code characters at 60 words per 
minute? Is that too fast for even assembly language? 
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SPECIFICATION: GIGO 

SOFTWARE PRODUCTS 

MORSE CODE GENERATOR 

PROGRAM, MORSE 

General Description 

This assembly-language software package is a 
TRS-80 Model I program that will run in systems 
with 16K of RAM or greater. It will generate 
international Morse code through the cassette output. 
Code generated will be either random code characters 
for practice purposes or a user-defined string of Morse 
code characters. Speeds of operation are user-defined 
and may be from 3 to 60 words per minute. 

Loading Procedure 

The MORSE package is loaded from disk by entering 
the command, MORSE, while in TRSDOS command 
mode. The MORSE program will be loaded and 
execution will start immediately. 

The MORSE package is loaded from cassette by 
entering the BASIC command mode. After the > 
prompt, the following sequence is entered to load and 
execute the MORSE program: 

•-, c n D " T " (Turn off real-time-clock in Disk BASIC) 

> SYSTEM (Enter Monitor mode) 

# ? M R S E (Load cassette tape file MORSE ) 

#?/ (Start execution after successful load) 

Operating Instructions 

After loading, MORSE will clear the screen and 
position the cursor to the "home" position at the upper 
left corner of the screen. It will also establish a 
communication area on the bottom three lines of the 
screen as shown in Figure 1. 

Pressing CLEAR at any time will "reset" MORSE and 
cause the following line to be displayed: 
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MORSE 




CHAR=SEND CHARACTER SHIFT 


-9 = SEND MSG N 


SHIFT R=3END RANDOM 




SHIFT D = DEFINE MSG SHIFT S = 


DEFINE SPEED 


SHIFT P »N = PRINT OR NO 




The above information is also displayed after loading. 



Figure 12-1. Specification 
for MORSE 





CUR&OR »HOM£ 
/ 


" POSITION 




1 


- TEXT AND MESSAGE 
DEFINITION AREA 
C 12 LINES) 














AREA 
(3 LINES ) 



Figure 1. MORSE Display 
Characteristics 



Normal operation: MORSE normally operates in the 
"send message" mode, where a single key stroke will 
send a character or one of 10 messages. Pressing a 
through 9 key with a SHIFT will send a predefined 
message through 9, while pressing the SHIFT R keys 
will send a string of random characters. If the 
message through 9 has not been defined, no action 
will occur. Transmission of message through 9 will 
continue at the current speed of operation until the 
end of the message is reached. At the end of the 
message, MORSE will await the next command. If a 
(R)andom string is being sent, transmission will 
continue indefinitely until the CLEAR key is pressed. 

At the same time a character, message, or random 
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characters are being sent, the message will be 
displayed on the screen and optionally printed on the 
system line printer (see "Line Printer Operation" 
below). 

Define Message Mode: The define message mode is 
entered by entering SHIFT D. After the SHIFT D has 
been pressed, MORSE will respond by the line 

DEFINE MESSAGE MODE, ENTER MESSAGE 
# 0-9; 

The user must then enter a valid message number 
through 9. If a valid message number is not entered, 
the line 

INVALID MESSAGE NUMBER, MUST BE 0-9 

is displayed, and the user must reenter the number. 
The user may simply press CLEAR to exit the Define 
Message Number mode. 

Once the message number has been entered, MORSE 
displays the line 

ENTER MESSAGE, TERMINATE BY ENTER 

The user can now enter the Morse code message to be 
stored as message number N. Valid characters for the 
message are the alphabetic characters A through Z, 
numeric digits through 9, period, comma, question 
mark, slash (/), and several special characters. The 
special characters are a dash, for "break" (-....-); space, 

for word space; semicolon for "error" ( ); and 

equals for "end message" (.-.-.). At the end of the 
message, the user presses the ENTER key. Invalid 
characters are ignored and are neither entered as 
part of the message, displayed, nor printed. 

The size of the message is limited to 256 bytes per 
message. MORSE checks the amount of memory used 
and will generate the error message 

MORE THAN 25G CHARACTERS, 256 ACCEPTED 
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if there is not enough space to store the current 
message. Only the first 256 characters of the current 
message will be stored if this condition occurs! 

Deletion of Messages: Messages may be deleted by 
entering the Define Message mode and pressing the 
ENTER key for message text. This action releases any 
previously allocated memory area to the system 
message area. 

Define Speed Mode: the Define Speed mode is entered 
by entering the keys SHIFT S during normal operation. 
MORSE responds with 

SET SPEED MODE. ENTER SPEED 3 TO GO WPM; 

The user must now enter an appropriate speed for 
message transmission, followed by an ENTER. If a 
valid speed is entered, the MORSE speed is set to that 
value. If an invalid speed is entered, MORSE will 
display the message 

INUALID SPEED. MUST BE 3 TO BO 

The user must then reenter a correct speed. 

The "default" speed of MORSE is 3 words per minute. 

Line Printer Operation: Messages may be optionally 
printed on the system line printer by pressing the 
keys SHIFT P during normal operation. Pressing the 
keys SHIFT N disables line printer operation. The 
system line printer must be capable of responding at 
the desired speeds. A speed of 60 words per minute, 
for example, is about 300 characters per minute or 5 
characters per second. If the printer has a long 
"carriage return" time without buffering data, some 
characters may be lost by certain types of slow 
printers. 

Random Character Generation: During this mode, a 
sequence of pseudo-random (repeatable) characters 
are generated. Comparison of code practice copy and 
the sequence may be performed by examination of 
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line printer or display output. 

Audio Output: Audio output from MORSE is through 
the cassette "AUX" output which would normally 
connect to the system cassette recorder. Audio output 
may be recorded directly on blank cassette tape and 
replayed, or the AUX output may be connected to an 
external audio amplifier. 

Amateur Radio Output: Amateur radio operators may 
use the audio output to key transmitters through 
appropriate circuitry of their own design. GIGO 
SOFTWARE, INC. can assume no liability in 
interfacing to such an application. 



In producing the specification, Cal drew upon his 
experience with similar types of programs. He did some 
preliminary computations that verified speeds of 60 words 
per minute could be obtained with no problems. One of the 
formulas he found gave the words per minute speed as — 
WPM = dots per second *2.4 

Working from this, Cal deduced that the fastest dot time 
would be 50 milliseconds, or 50,000 microseconds, or about 
10,000 instruction times. He concluded that this was slow 
for assembly language. However, this was a crucial stage. 
There were many other problems that may not be visible 
at this point, as we shall see. 
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Program Design 

Cal's next task was to produce a complete implementa- 
tion specification. This would be a specification that 
would discuss technical considerations of implementing 
the program. This step is often ignored for short programs 
and sometimes ignored for major programs involving 
many man years of work, much to the dismay of some 
companies. 

The implementation spec includes flow charts of all 
program code and may also include a text description of 
portions of the program. It may also define and specify 

system tables. 

Cal was too experienced a programmer to simply start 
coding the program. He knew that even for small jobs a set 
of flow charts uncovered many logic errors and helped 
him visualize the structure of the program. 

As for program structure, Cal usually used a combination 
of "top-down" and "bottom-up" design. The "top-down" ap- 
proach dictated the program be designed from major func- 
tions downward, finally culminating in the lowest level 
modules or subroutines. The "bottom-up" approach used 
the opposite tack: the program was first coded at the 
lowest level of routines, and then progressively more 
complicated routines were designed. 

Cal already had a preliminary spec that represented the 
"top-down" operation of the program. His job was now to 
implement the spec by defining program functional 
modules that would perform the logical functions of the 
program. A module is a collection of code performing a 
well-defined specific function with a set of inputs to 
produce a well-defined set of outputs. He knew that parts 
of the design would utilize old code, perhaps intact, such as 
a DELAY subroutine to delay a specified time. He also 
knew that other parts would be new code that he would 
have to write from scratch. 
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"Do you have your flow-chart template?" Cal asked Ted. 
"I've got to get this design done before I slip the schedule 
again." 

"Sorry, I used mine to scrape up the TRSDOS diskette I left 
out in the sun yesterday. The template melted, too." 
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' 'Standard' ' Flow Chart Symbols 

Here are some symbols commonly used in 
flowcharting: 




DECISION 
MAYBE 



PROCESSING 



OFF- PAGE 



ENTftY 



! /A J CONNECTOP. ( ENTER *) 



/V\ ON- PAGE , .TERMINATOR 
\ lx I mNMPrrnn , « ^ 



/ . xuN-mtot ,,TERMlf 
V J CONNECTOR / * \ 

v — / (done) 



■ - DELAY 

SUBROUTINE 



COMPUTE 
DELAY 



/OUTPUT / INPUT/ 
CHARACTER / OUTPUT 



Cal found a spare template and set to work. He did not 
simply produce page after page of flowcharts, but spent a 
great deal of time contemplating various aspects of the 
design, occasionally referring to reference materials or 
notes. 

Several days later, Cal was done with the flow charts. A 
sample of what he produced is shown in Figure 12-2. 
Although there are several standard flowcharting 
symbols, Cal used those which his company had 
established as their standard. They were similar to those 
used by most other programmers in defining programming 
operations — a rectangular box for "processing," a 
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diamond for a decision point, a "subroutine" symbol, on 
and off page connectors, etc. The important thing to Cal 
was that he produce a shorthand version of the program he 
was going to code in standard notation. 
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TIME 
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: igure 12-2. Flow Chart 
Example 




"Would you take a look at these when you get a chance?" 
Cal asked Ted. 

Cal's company had a policy of design reviews for major 
jobs. After a programmer had finished specifying and 
designing a large program, he would distribute copies of 
the implementation spec and flow charts to the other 
programmers in the department. Then, after each had had 
a chance to look them over, a general meeting would be 
held to review the design. 
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The meetings produced their share of nit-picking 
comments but also brought to light omissions or errors in 
most designs. 

Since this was a smaller program, Cal was not obligated to 
hold a design review, but he did want to have his 
officemate review the flowcharts to catch any obvious 
errors. 

"Oh, oh!" Ted exclaimed while looking over one page of the 
flowcharts. 

"What's the matter?" 

"I don't think you've thought this through! You've got the 
program picking up a character from the keyboard, con- 
verting it to Morse code, outputting the code through the 
cassette port, and then going back to pick up the next 
character." 

"Right — what's wrong with that?" 

"Well, that means that the next character typed can't be 
output 'til the last one is done!" 

"So?" 

"If you do that, the user has to wait instead of typing 
normally. He'd have to type a character, wait for the tone 
to stop, type the next . . . ." 

"Oh," Cal groaned, "I see what you mean. I need a 
buffered input that'll pick up keys even during output of 
characters!" 

Hints and Kinks 12-5 

The Problem 

If the input was not buffered, each character 
would have to be output before a new character 
was read from the keyboard. This doesn't seem 
annoying in theory, but in practice it would 
make for Morse code output that would have 
longer spaces than normal between characters 
and would inhibit the operator from typing 
freely . 
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"You didn't need this job, anyway!" Ted said with a grin 
and ducked as a copy of TRS-80 Assembly-Language Pro- 
gramming went flying by his head. 

Cal did some revision and came up with a new set of 
flowcharts. After another review by Ted, he was ready to 
do the coding. 

In the process of flowcharting, Cal defined several levels of 
modules. They are shown in Figure 12-3. The reader may 
want to refer to Figure 13-8 to see how they relate to the 
actual code of the program 
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Figure 12-3. Typical Program 
Modules 
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Coding 

Cal's flowcharts were such that he could have handed 
them to a junior programmer for coding. On larger jobs, 
there might be teams of programmers working on the 
project, each one coding his portion of the job after the 
implementation specification and flowcharting were done 
and reviewed. On this job, however, Cal did his own 
coding. 

With the flowcharts and spec done, the coding went very 
rapidly. Cal didn't use regular coding sheets, although 
many of the programmers did. He wrote his code in pencil 
on quadrille pads since he would be entering the code on 
the system himself. The company maintained data entry 
operators that would take coding on coding sheets and 
enter it into the system for assembly, but Cal preferred to 
avoid the local queues on smaller jobs and enter the code 
himself. 

Cal was very familiar with the Z-80 instruction formats, 
but remembered the problems he had had when he first 
started working with Z-80 code. It had taken him some 
time to get familiar enough with the instruction formats 
that he could automatically put down the correct form. 
Another problem had been the large number of instruction 
types available. Now, he rarely consulted the manual for 
instruction formats and operation. 

One thing that Cal made certain of was to put a comment 
on virtually every line of the program. He knew they 
would be invaluable not only months later, but would help 
days later in interpreting some of the instructions. 

Finally, the coding was done. Cal used his own TRS-80 in 
the office to enter the code and assembled the program. On 
the first assembly, he had several dozen assembly errors, 
most of them produced by a misspelled label. Correcting 
the errors, Cal reassembled, and after three edits and 
reassemblies got a "clean" assembly. 

He compared the assembly listing with his original code in 
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great detail, and then put the original code away in what 
he called his "coward's nook," a place he put material he 
thought he'd never use again but was afraid to throw 
away. 

Desk Checking 

Cal's next task was desk checking. In this step of 
producing the MORSE program, Cal went over the 
assembly listing in minute detail. He compared it with the 
flowcharts for logical errors and looked at each section of 
code for such things as registers destroyed in subroutines 
when they should not have been and errors in using the 
stack. 

On this last point, Cal paid particular attention to detail. 
He made certain there was a POP for every PUSH and a RET 
for every CALL, or at least a proper adjustment of the stack 
pointer. More than once he had had his program "gobbled 
up" by a hungry stack. 

On some of the code Cal "played computer" and used a 
paper and pencil to record the actual operation of a 
subroutine, just as the Z-80 would do. He drew a line with 
all Z-80 registers as a heading, assumed some initial entry 
data for the subroutine, and then laboriously went 
through instruction by instruction, decrementing 
registers, adding results, and counting loops. One of his 
sessions for the SCROLL subroutine is shown in Figure 
12-4. 
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As a result of the desk checking, Cal edited and 
reassembled twice again. The first time picked up some 
fairly important errors he had made in logic, while the 
second time cleaned up some minor problems he had found 
on the desk check after the first reassembly. Cal finally 
felt confident enough in the code to try on-line debugging. 



Hints and Kinks 12-6 



How Much Desk Checking? 

How much desk checking is necessary? If you 
were debugging on a large system with many 
programmers and limited access, you'd want to 
do a great deal of desk checking. On your own 
TRS-80, however, do enough to keep from being 
forced to reassemble more than about once 
every four hours of debugging time. This 
usually means a couple of passes through all 
the code initially with fairly close scrutiny. 
Find a comfortable trade-off between time 
spent in reassembling and time spent desk 
checking. 



"Ok, Ted, I'm going to run this turkey. Want to see it work 
the first time?" 

Ted raised his eybrow and said, "I almost had a program 
run the first time. Of course, it was only three instructions 
long ..." 

Debugging 

Actually, at this point, many of Gal's debugging problems 
were over. He had written a good implementation spec, 
flowcharted the program, had a one-man review, and had 
done comprehensive desk checking. The debugging task at 
this point would probably only be for minor oversights. 

Cal loaded MORSE and then created a disk file version by 
the DUMP command. Loading it in again, he used Disk 
DEBUG to start execution at location 8000H. The screen 
filled with "@@@@(cv(cv(a (0.(00..." and the disk "rebooted." 
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"That wasn't quite the result I expected," muttered Cal as 
Ted turned back to his desk. 

Cal debugged the program by using the "binary search" on 
errors we discussed in earlier chapters. By the end of the 
day, he had patched the program to the point where it ran 
through the initialization fairly successfully and even 
output a single character on the cassette audio. The next 
error he found, however, was one that was not easily 
patched, and he was forced to reedit and reassemble. 

It took Cal several more days of debugging to get to the 
point where he could find no more known errors. At that 
point he turned to his next task in the production cycle. 

Comprehensive Testing 

GIGO, Inc. was a software house producing software for 
the TRS-80 and other computers. The company had long 
ago learned to perform comprehensive tests on their 
software, rather than releasing it prematurely. Of course, 
there was constant pressure from Sales for a volume of 
interesting new products, but the Programming 
Department manager was firm in his resolve to eliminate 
as many bugs as possible before releasing the product (he 
was also the son-in-law of the chairman of the board). 

Cal spent several days drawing up a test plan that would 
exercise as many of the features of MORSE as possible. It 
included such things as a check to see that all characters 
would be properly output, that all speeds could be utilized, 
that all limit conditions (such as 256 characters per 
message) worked, and that there was an even distribution 
of random characters. 

When he finished, he had a formalized test plan on paper. 
This was submitted to his manager, Paul, and kept in the 
program file. Cal then went down the test plan step by 
step and tested each item. He found several minor 
discrepancies and several human factor improvements, 
such as the length of time that error messages were 
displayed on the screen. 
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After the last test item had been cleared up, Cal 
reassembled the "last version" of the program, went 
through the test plan again and found no errors. He knew 
that it was entirely possible that lurking in the depths of 
the MORSE program were small bugs that might grow their 
way to the surface when a user in Chillicothe decided to 
transmit four error codes together while using the printer 
during a quarter moon. He also knew that it was virtually 
impossible to eliminate all bugs except by continued 
testing over great lengths of time. However, he was 
confident that most users would be very happy with the 
program. 

With some trepidation, Cal walked into Paul's office and 
said, "Well, here it is, Paul — the final version of MORSE!" 

"Great, Cal. By the way, I'm glad you're here. I just got in 
a request to develop a TRS-80 program to learn Tic- 
Tac-Toe. . . ." 



Final Clean-Up 

Cal's work on MORSE wasn't quite done. He revised the 
final specs on the program and filed the specs, listing, 
source code, and working program. He knew the 
importance of this because when he first joined the 
company, he had to take two existing programs and 
correct errors that had been discovered. The programmer 
who had written them, "No Comment" Garigan, had left 
the company to become a tour guide in Pismo Beach. 

Garigan's code contained, as his nickname implied, 
virtually no comments on any lines. His flowcharts were 
incomplete, his design specs nonexistent. Since that time, 
Cal had made it a special point to be as thorough in 
documentation as possible. He knew it was entirely 
possible that one of those tiny bugs might become the 
"Monster That Ate the TRS-80" and that he himself might 
be forced to correct his own code. 
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No Resemblance to Programmers Living 

or Dead 

Although the scenario above is ficticious, it is an attempt 
to show an idealized situation in program design and 
development. Most programs are developed under less 
formalized steps, and many delete such important steps as 
flowcharting and final testing. In developing your own 
assembly-language programs, you'll adopt the methods 
that work for you, but it may actually take less 
development time to go through the procedures defined 
above ... so some programmer a year from now won't 
nickname you "No-Comment" Garigan! 

In the following two chapters, we'll show the flowcharts 
and listings for two large assembly-language programs: 
one for Morse Code Generation and one for a Tic-Tac-Toe 
program that "learns." These should clearly represent 
some of the elements of programming style that we've 
discussed. 
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Chapter Thirteen 
A Morse Code Generator Program 

In this chapter we'll look at the design and imple- 
mentation of a program to generate Morse code by audio 
tones sent to the cassette output port. The program may be 
used for code practice, or it may be used for amateur radio 
applications to record and playback messages and normal 
keyboard characters at speeds of 3 to 60 words per minute. 
One of the features of the program is that it is fully 
buffered — messages being typed on the keyboard may 
"overrun" the actual Morse code output and may be dozens 
of characters ahead. 

This program was designed as a typical assem- 
bly-language application for this book to illustrate some of 
the concepts discussed Chapter 12 on large program 
design and implementation. Since we'll also discuss the 
code in the program, we'll be tying together many of the 
coding concepts discussed earlier. 

General Specification 

The general specification for the program is shown in 
Figure 12-1. (Only the name has been changed from 
"MORSE" to "MORG".) The program has basically three 
modes. The first mode is keyboard output. Characters 
typed on the keyboard will be output as audio-frequency 
Morse code characters from the cassette output (the plug 
that normally attaches to the cassette recorder "AUX" 
jack). A small, inexpensive amplifier can be used to play 
the resulting output through a small speaker. As 
characters are output, they are displayed on the screen 
and can be printed on the system line printer. 
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The second mode of operation is integrated with the first. 
You can generate predefined messages of up to 256 
characters in length by a single keystroke. Up to ten 
messages can be defined and generated, and you can 
intersperse messages and normal text. As characters are 
output, they are displayed on the screen and optionally 
printed on the system line printer. A typical message 
might be defined as message 5 and read CO CO 
CO DE WDGCTY WD6CTY WDGCTY K. Every time you 
pressed the "SHIFT, 5" keys, this message would be 
generated. 

The third mode of operation functions independently of the 
other two. With Random mode, you can generate an 
endless string of pseudo-random characters for code 
practice. As the characters are output to the cassette port, 
they are displayed on the screen and can be printed on the 
system line printer. The speed of operation of any of these 
modes can be defined to be 3 to 60 words per minute. 

Operation 

After loading, MORG clears the screen, draws a line near 
the bottom to define a "communication area," and outputs 
a title message of 

MORG 

CHAR = SEND CHARACTER SHIFT 0-9 = SEND MSG N 
SHIFT R = SEND RANDOM SHIFT D = DEFINE MSG 
SHIFT S = DEFINE SPEED SHIFT P,N = PRINT OR NO 

You can now choose one of the options in the title message. 
To define the speed, you press SHIFT S and enter a speed 
value of 3 to 60 words per minute. After the speed is 
defined, the title message is again printed. To set 
simultaneous printing on the system line printer, you 
press SHIFT P. The line printer will now echo the Morse 
characters displayed on the screen. To disable the printer 
at any time, you press SHIFT N. Both actions terminate by 
display of the title message. To define a message, you 
press SHIFT D. The define message mode is now entered 
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and will prompt you to input a message number of 
through 9 and to enter the text of the messge. Any number 
of characters may be entered for the text up to 256. You 
terminate the message by an ENTER key press, bringing 
you back to the title message display. 

To output characters and messages, you can type in 
characters from the keyboard. Each time you type a 
legitimate character, there is an output in Morse code 
from the cassette output at the currently defined rate of 
speed. Illegitimate keys are ignored. Each time you enter 
a SHIFT (followed by through 9) the previously defined 
corresponding message will be output in its entirety. If no 
message has been defined, nothing will be output. As 
keyboard text or messages are output, the text is 
simultaneously displayed on the screen and output to the 
system line printer if Print has been set. 

If you have chosen the Random mode by SHIFT R, a 
continuous stream of pseudo-random text will be output to 
the cassette port, simultaneously displayed on the screen, 
and (optionally) printed on the system line printer. The 
speed will be at the currently defined rate of speed. The 
Random mode simulates normal text by inclusion of spaces 
at regular intervals. 



Hints and Kinks 13-1 — 

Simulating Text 

Text is simulated here by including spaces in 
the CTAB, the 128-byte table of random 
characters. There are 18 spaces out of 128 
characters, making the frequency about a space 
every six characters. The program also checks 
to make certain that two spaces are not sent 
consecutively. 



Legitimate characters are the alphabetic characters A 
through Z, digits through 9, comma (,), period (.), slash 
(/), question mark (?), and three special characters. The 
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three special characters are a dash for a "break" (—....—), 
an equals for end of transmission (.—.—.), and a semicolon 
for "error" ( ). All other characters are ignored. 



General Design 

The general design considerations or research into the 
methods of Morse code generation can be broken down into 
the following areas: 

• Characteristics of Morse code 

• Generation of audio tones 

• Keyboard read routines 

• "Buffering" 

• Conversion to Morse code characters 

• Message storage and search 

We'll discuss each of these areas, the alternative methods 
that could have been used, and the final method that was 
adopted in MORG. 



Characteristics of Morse Code 

Morse code consists of a series of dots and dashes to 
represent alphabetic, numeric, and special characters as 
shown in Figure 13-1. A dot is defined as a short burst of 
an audio tone or other signal, while a dash is a longer 
tone. The combinations of dots and dashes used are 
generally based on the frequency of the letter in normal 
text. An "e" for example is one dot, while a "q" is dash, 
dash, dot, dash. The special character question mark (?) is 
dot, dot, dash, dash, dot, dot. 
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Figure 13-1. Morse Code Symbols 

The relationship of dots, dashes, spaces between dots and 
dashes, and spaces between words is shown in Figure 13-2. 
A dot time is the basic unit, a dash time is three units, the 
time between dashes and dots is one unit; the time 
between characters is three units; and the time between 
words is five units. When an audio tone is used for the 
Morse code, the tone is on during the dot or dash time and 
off during the spaces as shown. 



DOT TIME = 1 = BASIC UNIT 

DASH TIME = 3 = 3 DOT TIMES 

SPACE BETWEEN DOT OR DASH=1 = 1 DOT TIME 

SPACE BETWEEN CHARACTERS = 3 = 3 DOT TIMES 

SPACE BETWEEN WORDS=5=5 DOT TIMES 
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Figure 13-2. Morse Code Spacing 
and Audio 
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A slow speed for Morse code transmission is 5 words per 
minute. This is the speed used for the amateur radio 
"novice" code qualifying test. Average speeds are fifteen 
words per minute, while high-speed "brass pounders" send 
at rates of 35 words per minute or greater. 

An average word is 5 characters, making the number of 
characters per minute 5*WPM (Words Per Minute). Fifteen 
WPM is therefore about 75 characters per minute, or about 
1.25 characters per second. The average number of dots 
and dashes in a character is hard to define. One formula 
relates the number of WPM to dots per second: 

WPM=DPS*2.5 

This would mean that 10 dots per second are equivalent to 
25 WPM. We'll use this formula for our analysis in MORG. 

In MORG, the code speed may vary between 3 and 60 WPM, 
allowing for a very slow user and a very fast one. The 
number of dots per second for 3 WPM is 1.2; the number of 
dots per second for 60 WPM is 24. Since a string of dots 
consists of a dot on time and a dot off time, this makes the 
dot duration: 

Dot duration in milliseconds = 1200/WPM 

For example, the duration of a dot at 3 WPM is 1200/3, or 
400 milliseconds, while the duration of a dot at 60 WPM is 
1200/60, or 20 milliseconds. On the surface, it appears that 
an assembly-language program should have no problem in 
achieving these speeds, since 20 milliseconds, the most 
stringent case, represents 4000 Instruction times at 5 
microseconds per instruction (5 microseconds*4000 = 
20000 microseconds or 20 milliseconds). 

The assembly-language program's main concern is to turn 
on an audio tone, leave it on for lengths of time ranging 
from 20 milliseconds (60 WPM dot) to 1.2 seconds (3 WPM 
dash), and turn it off. 
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Generation of Audio Tones 

As we know from Chapter 10, you can easily use the 
TRS-80 to generate a wide range of audio tones. In this 
case, we need to generate only one frequency, unless we 
choose to make the pitch variable. 



Hints and Kinks 13-2 

Generating Tones 

You can accomplish tone generation here by 
1 'toggling' ' the cassette output latch on and 
off. You output alternating 01s and 10s to the 
cassette latch address OFFH. The 01 causes a 
1 'high' ' level, and the 10 causes a ' 'low' ' 
level. A zero reference level would be created 
by 00. 



The audio tone will be on for a dot or dash on time and off 
for inter-character or inter-word spacing. Our only 
problem would be the shortest duration dot-time that will 
have to be handled. Does this represent a duration during 
which we can generate a tone or is the duration so short 
that we can't toggle the cassette latch on and off to 
produce a tone? 

The shortest duration dot-time from above is 20 milli- 
seconds. During that 20 milliseconds, we must toggle the 
cassette latch on and off several times. If we did it one 
time, on and off, the period of the tone produced would be 
20 milliseconds. 



291 



As the frequency of such a tone is 1/period, or 50 cycles 
per second, there seems to be no problem in the tone. Fifty 
cycles per second is too low for both comfortable listening 
and amplification on an inexpensive amplifier. If we tried 
for 500 cycles per second (500 hertz), we would be toggling 
the cassette latch ten times on and off for the shortest 
duration dot, which would be fine. 

Keyboard Read Routines 

We know from Chapter 7 that we can hand-tailor a keyboard 
read routine to read any key and convert it to whatever 
character we want. In most cases here, we'll be doing a 
"straight" conversion into the ASCII code associated with the 
key. However, we will have to convert some keys into special 
codes to represent characters for "end of message," "error," 
and the like. Still, we should have no problem in the 
conversion. 



Buffering Keyboard Input 
& Polling the Keyboard: Problems 

There will be a problem in the area of keyboard speed, 
however! The specification allows for buffering keyboard 
input. This means we can be typing at a faster rate than 
the data is being transmitted in Morse code audio. We'll 
have to store the characters in some sort of large buffer, 
depending upon how many characters ahead we wish to 
store. 

This also means that as the character is being 
transmitted, we must poll the keyboard to see if the next 
character is being input. If it is, we must debounce the 
character and store it in the buffer. What other problems 
do we face at this point? 

One major problem is this: If we use a time-delay-loop in 
order to generate the on/off times that toggle the cassette 
latch to produce an audio tone, we can't be going out 
during the generation of dots and dashes to poll the 
keyboard! 
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Hints and Kinks 13-3 

Debouncing 

Debouncing works like this: When a key is 
depressed, it bounces up and down in the space 
of fractions of milliseconds, making and 
breaking the contact. When a key is released, 
the same make and break occurs. Keys are held 
down for approximately l/50th of a second. The 
make/break diagram looks roughly like this: 

PRESS RELEASE 

MAKE 



BREAK. 



KEY HELD DOWN 
>/s0 SEC TYPICAL 



"Rollover" allows the next key to be detected 
when a previous key is still being held down. 
MORG does not have rollover, but looks for the 
next key 100 milliseconds or so from the last. 
This would allow for typing speeds up to 120 
words per minute. 

Debouncing detects the first "make" and then 
waits 100 milliseconds to bypass bounce on the 
press and release. 



Scanning (or polling) the keyboard normally takes 50 to 
100 milliseconds (l/20th to 1/10 second) because the 
character has to be debounced. If we wait this long to 
debounce a character that's being input, it'll extend the 
dot or dash time for high-speed transmission (for instance, 
a dot-time for 20 WPM is 60 milliseconds). If we delay 50 
milliseconds to debounce, the dot-time changes to 110 
milliseconds! This is clearly unacceptable. 

What to do, what to do .... On the one hand, we need to 
be able to read the keyboard during transmission of 
characters to eliminate a tedious "wait until complete 
before reading keyboard" condition. On the other hand, it 
appears we can't debounce the character because it will 
affect the dot and dash times. 
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Buffering & Polling: Some Solutions 

Is there any other way to time-out the bounce? If there 
were, we could rush out for a fraction of a millisecond or so 
during dots, dashes, or spaces and check to see if a key 
were pressed. If a key were pressed, we could quickly 
decode the key and store it in a buffer, start some sort of 
timer, and then go back to the dot/dash/space generation. 
We could then periodically check for an elapsed time of 50 
milliseconds or so. If 50 milliseconds had elapsed, we could 
reset the timer and go back and repeat the process again. 

A disk system would certainly let us perform the timing 
since it counts in increments of 25 milliseconds. But we 
may not have a real-time clock if we don't have a disk 
system. Is there some way to emulate the real-time-clock 
function? 

One way would be to establish a counter inside our 
program. This software counter would count in increments 
of 1 millisecond. As we'll be using a subroutine to time the 
cycles of the audio tone, we could use the delay count for 
the delay subroutine to increment the counter by the 
number of milliseconds delayed. For a continuous stream 
of characters, this would give us a fairly accurate count of 
elapsed time. 

However, we don't have a continuous stream of characters, 
do we? Sure, some times we've buffered a large number of 
characters, and they keep on being generated at the 
current speed. But what about the case where the user is 
doing a "hunt and peck" at the keyboard? If the counter is 
only incremented during the time delays for the audio 
tones, it certainly won't be a record of elapsed time. 

Well, we'll be looping and waiting for that next character 
from the keyboard and that loop should be at a fairly 
constant speed. We can establish an increment of the 
software millisecond counter every "n" times through the 
loop. This should work for the rough elapsed time needed 
for debounce. After all, it doesn't matter too much whether 
we delay 50 milliseconds or 100 milliseconds for a 
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maximum typing speed of 60 WPM (or five characters per 
second). Is this the best way to handle this problem? 
Probably not, but it's one way given the constraints of the 
system — no real time clock, no interrupts, and a need for 
buffering. 

To minimize the time required to rush out and poll the 
keyboard, we'll need a fast keyboard scan routine, one that 
determines quickly if a character is there, and if not, 
returns to the calling routine. It'll also have to test for the 
debounce delay time from the software counter. 

Buffering 

What about the problem of buffering? How do we store 
the characters as they are read in and then transmit 
them? 

To do this we'll need a buffer of a certain number of bytes. 
As the characters are read from the keyboard, they are 
stored in the next slot of the buffer. The cassette tone 
output will have to somehow test the contents of the buffer 
to see if there is any new character available for output. 

If the operator is a very slow typist and the code speed is 
slow enough, this buffer will be filled with one character 
and then immediately emptied. However, if the operator is 
fast and the code speed is slow, the buffer may fill up 
rapidly with characters that are being input too fast to be 
handled. 

What about the size of the buffer? If the program runs for 
any length of time, we'd need a very large buffer. A better 
way to do this would be to establish a circular buffer 
based on the worst-case input and output speed. We'll 
assume that the operator can't get more than 256 
characters ahead before he gets confused! This should be 
adequate for most of us. 

The circular buffer is used as shown in Figure 13-3. A new 
character goes into the next slot. A pointer to the next slot 
is then incremented by one. If we reach the end of the 
buffer, the pointer is set back to the beginning of the 
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buffer. A second pointer points to the "next character 
available." If the two pointers are equal, all characters 
have been used. "Overrun" is possible if the number of 
unused characters exceeds 256. 



KEYBOARD HAS ACCEPTED: TRS-SO IS 
PROGRAM HAS SENT: TRS- 



POINTER TO NEXT CHARACTER 



POINTER TO NEXT SLOT 



WHEN CHARACTER HAS 
BEEN STORED HERE, 
"POINTER TO NEXT SLOT" 
RESETS TO BEGINNING 



Figure 13-3. Circular Buffer 

Conversion to Morse Code Characters 

How will a given ASCII character be converted to a Morse 
code character? We have 26 alphabetic characters, ten 
digits, blank, and seven special characters to be concerned 
with. The Morse code combinations are completely 
unrelated to ASCII codes or to any other "neat" method of 
finding the proper combination of dots and dashes. 
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The implication is that instead of a formula or 
algorithmic means to produce the Morse code, we need to 
translate an ASCII character into a Morse code character 
by a table lookup. One Morse code configuration will be 
in the table for each legitimate ASCII character. 

What about storage of the dots and dashes in the table? 
Each character we're concerned with is represented by six 
or fewer dots or dashes, except for the "error" code. It looks 
like we could use six codes for each character. One way to 
do this would be to store a fixed eight-byte entry for each 
character, with representing a dot, 1 a dash, 2 a space, 
and -1 a terminator (or we could pack two codes in each 
byte). 

After some thought, we came up with this: Each 
combination of dots and dashes is held in 16 bits, or two 
bytes. There are eight fields in the two bytes. Each field 
contains a two-bit code. A code of 00 represents a dot, a 
code of 01 represents a dash, a code of 10 is a dot space, 
and a code of 11 is a terminator. The 8 fields read from 
right to left. Each combination ends with a terminator 
field of 11, allowing up to seven dots, dashes, or dot spaces, 
plus a terminator. 

This scheme is shown in Figure 13-4. 



00 00 00 II 


01 0i 00 01 



END DASH DASH DOT DASH 

V T / 

READ FROM RIGHT TO t-EFT 



00 = DOT DASH DOT 

81 = DASH 
10 = SPACE 
11=TERMINATOR 



Figure 13-4. Dot, Dash, Space 
Coding 



The special case of eight dots ("error code") is represented 
by two bytes of zeroes and is detected in the program. 
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Message Storage and Search 

Messages are stored as ASCII character strings. A large 
buffer capable of holding 10*257 + 1 or 2,571 characters 
(and ten one-byte "headers") is established. A minus one is 
used as a terminator for the last message in the buffer. 
Unused spaces in the buffer are filled with minus one 
bytes. 

All bytes in the buffer are either valid ASCII characters, 
minus ones, or the binary digits through 9. A binary 
digit through 9 marks the header of a message string. 
The length of the string is determined by the next 
occurrence of a digit, or a minus one. 

Messages are put into the buffer as they are defined. A 
search is made for the header number to find a specified 
message. If a message is redefined, the old message is first 
deleted by "moving up" the remaining buffer into the 
space previously occupied by the message. This approach 
is shown in Figure 13-5. 

OLD NEW 



MESSAGE = 


"TEST" 




"TEST" 


5= "TRS-80" "NEXT" 




3 = 


"LAST" 




"LAST" 















T 


T 


T 


E 




E 




E 


S 




S 




S 


T 




T 




T 


5 


3 


3 


T 


L 


L 


R 




A 




A 


S 




S 




S 


ift 




T 




T 


-1 


5 


N 

E 
X 


3 


L 


A 
S 




— 1 




T 


-1 


T 




-1 




-1 

-1 


-1 


-1 


-1 




-1 




-1 


MESSAGE 5 
IS TO BE 
CHANGED 


DELETE MES- 
SAGE 5 BY 
MOVING UP 
REMAINDER 


ADD NEW 
MESSAGE 5 
TO END OF 

MESSAGES 






OF BUFFER 







Figure 13-5. Message Storage 
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Implementation 

Modules 

MORG is implemented as a series of five levels of modules, 
shown in Figure 13-6. The top level of modules is the main 
driver of the program. The bottom level of modules are 
the most rudimentary subroutines of the program. 



"HIGHEST LEVEL 










DRIVER 


LEVEL 1 












DEFINE 


SPEED 


RANDOM 


XMIT 


PRINT 


NOPRNT 


LEVEL 2 


FNDMSG 


SNDCHR 


DSPMES 


LPRINT 


DISCHR 


SCROLL 


CLRCOM 


INPUTS 






INPUT 


INPUTW 


GETCHR 


RAND 


LEVEL 4 


LOWEST 

LEVEL" 


SHIFT 


SUB 


FILLCH 


DECBIN 


DELAY 


LEVELS 



Figure 13-6. MORG Modules 
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The modules are generally dedicated to a particular 
well-defined function related to the MORG application, 
such as "finding a message number" or "clearing the 
communications area." Each module is generally in the 
form of a subroutine with one entry point and one exit 
point. The lowest level of subroutines are general-purpose 
subroutines, useful for many applications. 

Figure 13-7 shows the modules and their interconnections. 
Each module generally calls another module by a CALL, 
with a set of parameters in the CPU registers. Higher level 
modules usually call lower-level modules, although some 
modules call other modules on the same level. 



Hints and Kinks 13-4— ■ 

Notes on Figure 13-7 

The module interconnection diagram of Figure 
13-7 reveals some interesting facts about the 
structure of MORG. The level one driver not 
only calls every level two routine but also 
does applications-related processing by 
calling level three routines, which are 
special purpose routines for the Morse code 
application. Level two routines also make 
heavy use of level three routines. 

If we see only one connection (dot) along any 
horizontal connection to a module, it might 
indicate that the modules should be 
incorporated as ''in-line 1 ' code. This occurs 
for SHIFT, SUB, and RAND. 



300 



0) 

3 

•a 
o 



s 


(A 

c 


(5 
DC 


U 


O 


0) 


m 


L. 
C 


. 


o 


N 


o 


■ 


u 


CO 


CD 


▼- 


■*-« 


(D 


C 


u 




3 




O) 




u. 





f 13A3T ■ 



301 



To find the modules called by any particular module, 
follow the horizontal line from the module to the extreme 
left. When the line turns downward, read the lower level 
module called by referencing the connection dots. The 
arrangement of the modules is duplicated in the program 
listing, that is, higher-level modules appear first, followed 
by lower-level modules. 

Tables, Buffers, and Variables 

Refer to the MORG listing, Figure 13-8. Here is a set of 
variables, buffers, and tables the program uses to define 
system status, hold text, and facilitate conversion. The 
variables are held in the working storage area of the 
program, near the end. For the most part, their use is 
explained by the comments associated with each one. 



6000 




00100 




ORG 


8000H 








001 10 


:MORG-0820 










00120 


. BaaaBBflsflfi&flfia 


MORSE CODE GENERATOR pR0GRAM a »»««»»»» ilB «» a 






00130 














00110 














00150 


; BaaeaBaaaaaaaaasaBaasYSTEM EQUATES »BB»BfisasfisssBBBSBfiflfis 






00160 










3C00 




00170 


SCREEN 


EQU 


3C00H 


START OF VIDEO DISPLAY 


3M0 




00180 


LINE1 


EQU 


SCREEN+64 


SECOND LINE 


3EC0 




00190 


LINE1 1 


EQU 


SCREEN+704 


TWELFTH LINE 


3F00 




00200 


LINE12 


EQU 


SCREEN+768 


THIRTEENTH LINE 


3F40 




00210 


LINE13 


EQU 


SCREEN+832 


FOUTEENTH LINE 


3F80 




00220 


LINE14 


EQU 


SCREEN+896 


FIFTEENTH LINE 


3FC0 




00230 


LINE15 


EQU 


SCREEN+960 


SIXTEENTH LINE 


0002 




00210 


ENTER 


EQU 


2 


ENTER CHARACTER 


0001 




00250 


CLEAR 


EQU 


1 


CLEAR CHARACTER 


0061 




00260 


DBDEL 


EQU 


100 


DEBOUNCE DELAY IN MS 


0065 




00270 


DBDELP 


EQU 


DBDEL+1 


DEBOUNCE DELAY+1 MS 


000A 




00280 


MLDEL 


EQU 


10 


MAIN LOOP DELAY IN 1/10 MS 


03C0 




00290 
00300 


SPEEDF 


EQU 


960 


FINAGLE FACTOR FOR SPEED 






00310 


; BBBBfifl 


BBBBB.BBBB.BB. MORSE F/XECU 


■JVEBBBBBBBfiBfiBBBBfifiBBfiBa 






00320 


; 








8000 


F3 


00330 


START 


DI 




DISABLE INTERRUPTS 


8001 


315991 


00310 




LD 


SF, TOPS 


SET STACK POINTER 


80014 


1 1EA88 


00350 




LD 


DE.MBUF 


MESSAGE BUFFER ADDRESS 


800T 


010B0A 


00360 




LD 


BC, 2571 


2571 BYTES 


800A 


3EFF 


00370 




LD 


A.OFFH 


-1 FOR FILL 


800C 


CD8385 


00380 




CALL 


FILLCH 


FILL MESSAGE BUFFER 


800F 


21D204 


00390 




LD 


HL, 1234 


INITIALIZE RANDOM t SEED 


80 12 


22E185 


00100 




LD 


(SEED) ,HL 




8015 


212E16 


001 10 




LD 


HL.5678 




80 18 


22E385 


00420 




LD 


(SEED+2) , HL 




801B 


3E20 


00430 




LD 


A. ' ' 


BLANK CHARACTER 


801D 


11003C 


0440 




LD 


BE, SCREEN 


START OF SCREEN 


8020 


010001 


00450 




LD 


BC, 1024 


« OF BYTES 


8023 


CD8385 


0460 




CALL 


FILLCH 


CLEAR SCREEN 


8026 


3E8F 


00470 




LD 


A.08FH 


ALL ON GRAPHICS CHAR 


8028 


11003F 


00480 




LD 


DE.LINE12 


LINE 12 


802B 


014000 


004 90 




LD 


BC.64 


# OF BYTES 


802E 


CD8385 


00500 




CALL 


FILLCH 


DRAW LINE 


8031 


21003C 


00510 




LD 


HL. SCREEN 


SCREEN START 


8031 


22E985 


00520 




LD 


(CURCUR) ,HL 


INITIALIZE CURRENT CURSOR 






00530 


: REENTER HERE 


FOR HOST FUNCTION 




8037 


216100 


00540 


HOR015 


LD 


HL, DBDEL 


DEBOUNCE DELAY IN MS 


803A 


CDC085 


00550 




CALL 


DELAY 


DELAY 


803D 


216500 


00560 




LD 


HL, DBDELP 


MINIMUM DELAY +1 
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801)0 22ED85 

8013 21F592 

80146 22F085 

801)9 22F285 

801 C 2AE985 

804F 22EB85 

8052 CDFB83 

8055 21F485 

8058 01403F 

805B CD6D83 

805E 2AEB85 

8061 22E985 



8064 
8066 
8069 
806C 
806E 
806F 
8070 
8072 
8071 
8077 
8078 
807B 
807D 
807E 
8081 
8083 
8084 
8086 
8087 
8089 

808B 
808E 
8090 
8093 
8096 
8097 
8099 
809C 
809F 
80A2 
80A5 
80A6 
80A9 
80AB 
80AC 
80AD 
80AF 
80B1 
80B5 
80B7 
80BA 
80BD 



1600 

CD2984 

CD1585 

200F 

14 

7A 

FEOA 

20F2 

2AED85 

23 

22ED85 

18E7 

BO 

21CC80 

060F 

BE 

2825 

2B 

10FA 

E67F 

32DC85 

3EFF 

32DD85 

21DC85 

7E 

FE20 

FA6480 

CDBE83 

CD8183 

CDE082 

23 

CD29811 

18EB 

48 

OD 

0600 

CB21 

DD21CD80 

DD09 

DD6601 

DD6E00 

E9 



80BE C4 

80BF D3 

80C0 D2 

80C1 BO 

80C2 B1 

80C3 B2 

80C4 B3 

80C5 B4 

80C6 B5 

80C7 B6 

80C8 B7 

80C9 B8 

BOCA B9 

80CB DO 

80CC CE 
OOOF 



00570 
00580 
00590 
00600 
00610 
00620 
00630 
00640 
00650 
00660 
00670 
00680 
00690 
0700 
00710 

0720 
00730 
00740 
00750 
00760 
00770 
007 80 
00790 
00800 
00810 
00820 
00830 
00840 
00850 
00860 
00870 
00880 
00890 
00900 
00910 
00920 
00930 
00940 
00950 
00960 
00970 
00980 
00990 
01000 
01010 
01020 
01030 
01040 
01050 
01060 
01070 
01080 
01090 
01100 
01110 
01120 
01130 
01140 
01150 
01160 

01 170 
01 180 
01190 
01200 
01210 
01220 
01230 
01240 
01250 
01260 
01270 
01280 
01290 
01300 
01310 
01320 
01330 
01340 



LD 
LD 
LD 

LD 

LD 

LD 

CALL 

LD 

LD 

CALL 

LD 

LD 
; REENTER HERE 
H0R020 LD 
MOR021 CALL 

CALL 

JH 

INC 

LD 

CP 

JR 

LD 

INC 

LD 

JR 
M0R022 OR 

LD 

LD 
MOR025 CP 

JR 

DEC 

DJNZ 

AND 
; NOT FUNCTION 

LD 

LD 

LD 

LD 
H0R0 27 LD 

CP 

JP 

CALL 

CALL 

CALL 

INC 

CALL 

JR 
HO BO 30 LD 

DEC 

LD 

SLA 

LD 

ADD 

LD 

LD 

JP 



FUNCTION TABLE 

CAB DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 

DEFB 
CABS EQU 

BRANCH TABLE 



(TSLC) , HL 
HL.IBUF 

(IBUFL) , HL 

( IBUFN) , HL 

HL, (CURCUR J 

(LSTCUR).HL 

CLRCOM 

HL.MSG1 

BC, LINE13 

DSPHES 

HL, (LSTCUR ! 

(CURCUR) , HL 
DURING TRANSMISS 

D,0 

INPUT 

CETCHR 

NZ.HOR022 

D 

A, D 

HLDEL 

NZ.M0R021 

HL, (TSLC) 

HL 

(TSLC) ,HL 

HOR020 

B 

HL.FTAB+FTABS-1 

B, FTABS 

(HL) 

Z.M0R030 

HL 

M0R025 

7FH 
HERE - TRANSMIT . 

! TM P 1 i , A 

A.OFFH 

(THP1+1 ) , A 

HL.TMPI 

A,(HL) 

M,MOH020 

DISCHR 

LPRINT 

SNDCHR 

HL 

INPUT 

HOR027 

C,B 

C 

B,0 

C 



IX 


,BTAB 


IX 


,BC 


H, 


( IX+1 ) 


L, 


( IX) 


(HL) 



+ 80H 
+ 80H 
+ 80H 
+ 80H 
+ 80H 
+ 80H 
+ 80H 
+ 80H 
♦ 80H 
+ 80H 
+ 80H 
+ 80H 
+ 80H 
+ 80H 
+ 80H 
FTAB 



INITIALIZE FOR NEXT CHARACTER 
INPUT BUFFER ADDRESS 
INITIALIZE INPUT BUFFER PNTRS 

;GET CURRENT CURSOR 
;SAVE 

: CLEAR COMMUNICATIONS AREA 
; INITIAL MESSAGE 
;LINE 13 
;OUTPUT MESSAGE 
:OET OLD CURSOR 
;RESTORE 
ION OF CHARACTERS OR MSGS 
i INITIALIZE MINOR COUNT 
GET RESPONSE 
GET CHARACTER 
GO IF PRESENT 
BUMP MINOR COUNT 
GET COUNT 
TEST FOR 1 MS 
GO IF NOT 1 MS 
GET TIME 
BUMP BY I MS 
RESTORE 
CONTINUE 
;MERGE SHIFT BIT 
; FUNCTION TABLE END ADD 
;FUNCTION TABLE SIZE 
iTEST FOR FUNCTION 
;G0 IF FOUND 
; POINT TO NEXT FUNCTION 
; CONTINUE 
;RESET BIT 7 
SINGLE CHARACTER 
STORE IN TEMP BUFFER 
-1 

STORE TERMINATOR 
ADDRESS OF "MESSAGE" 
;GET NEXT CHARACTER 
;TEST FOR NON-ASCII 
;G0 IF END OF MESSAGE 
^DISPLAY CHARACTER 
;PRINT IF REQUIRED 
;SEND CHARACTER 
; POINT TO NEXT 
;TEST FOR INPUT 
; CONTINUE SENDING 
INDEX+1 NOW IN C 
ADJUST FOR INDEX 
INDEX NOW IN BC 
2'INDEX NOW IN BC 
BRANCH TABLE 
POINT TO BRANCH 
GET MSB OF ADDRESS 
GET LSB OF ADDRESS 
BRANCH OUT 



DEFINE MESSAGE 
DEFINE SPEED 
TRANSMIT RANDOM 
TRANSMIT MESSAGE 



SET PRINT 

RESET PRINT 

SIZE OF FUNCTION TABLE 
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80CD 


EB80 


01350 


8ocf 


9181 


01360 


80D1 


F081 


01370 


80D3 


3782 


01380 


80D5 


37 82 


01390 


80D7 


3782 


01400 


80D9 


3782 


01410 


80DB 


3782 


01420 


80DB 


3782 


01430 


80DF 


3782 


01440 


80E1 


3782 


01450 


80E3 


3782 


01460 


80 E5 


3782 


01470 


80 E7 


8B82 


01480 


80E9 


B182 


01490 
01500 
01510 
01520 


80EB 


2AE985 


01530 


80EE 


22EB85 


01540 


80F1 


CDFB83 


01550 


80 F4 


21F586 


01560 


80F7 


01403F 


01570 


80FA 


CD6D83 


01580 


80FD 


0601 


01590 


80FF 


CD0D84 


01600 


8102 


C27F81 


01610 


8105 


0601 


01620 


8107 


CD9085 


01630 


810A 


C27F81 


01640 


810D 


7D 


01650 


810E 


21C987 


01660 


81 11 


O1803F 


01670 


81 14 


CB6D83 


01680 


8117 


2AEB85 


01690 


81 1A 


22E985 


01700 


81 1D 


F5 


01710 


81 1 E 


CDC782 


01720 


8121 


202A 


01730 
01740 


8123 


E5 


01750 


8124 


D1 


01760 


8125 


23 


01770 


8126 


7E 


01780 


8127 


FE20 


01790 


8129 


FA2F81 


01600 


812C 


23 


01810 


812D 


18F7 


01820 


812F 


E5 


01830 


8130 


C1 


01840 


8131 


E5 


01850 


8132 


21F592 


01860 


8135 


B7 


01870 


8136 


ED42 


01880 


8138 


E5 


01690 


8139 


CI 


01900 


813A 


E1 


01910 


813B 


EDBO 


01920 


8130 


21F592 


01930 


8140 


B7 


01940 


8141 


ED52 


01950 


8143 


E5 


01960 


8144 


CI 


01970 


8145 


3EFF 


01980 


8147 


CD8385 


01990 


814A 


CDC782 


02000 
02010 


814D 


Fl 


02020 


814E 


77 


02030 


814F 


23 


02040 


8150 


0600 


02050 


8152 


CDF384 


02060 


8155 


FE02 


02070 


8157 


CA3780 


02080 


815A 


77 


02090 


815B 


23 


02100 


815C 


CDBE83 


02110 


815F 


10F1 


02120 


8161 


2AE985 


02130 



DEFW 


DEFINE 


DEFW 


SPEED 


DEFW 


RANDOM 


DEFW 


XHIT 


DEFW 


XMIT 


DEFW 


XHIT 


DEFW 


XMIT 


DEFW 


XHIT 


DEFW 


XHIT 


DEFW 


XHIT 


DEFW 


XMIT 


DEFW 


XMIT 


DEFW 


XMIT 


DEFW 


PRINT 


DEFW 


NOPRNT 



DEFINE MESSAGE 
DEFINE SPEED 
TRANSMIT RANDOM 
TRANSMIT MESSAGE 
1 
2 
3 
4 
5 
6 
7 



SET PRINT 
RESET PRINT 



»»sfiSflaflfiffa»»aii*DEFINE MESSAGE N ROUTINE" 99 ***** 8 *" »*** 



DEFINE LD 

LD 
DEF005 CALL 

LD 

LD 

CALL 

LD 

CALL 

JP 

LD 

CALL 

JP 

LD 

LD 

LD 

CALL 

LD 

LD 

PUSH 

CALL 

JR 
; CURRENT MSG F 

PUSH 

POP 

INC 
DEF025 LD 

CP 

JP 

INC 

JR 
DEF030 PUSH 

POP 

PUSH 

LD 

OR 

SBC 

PUSH 

POP 

POP 

LDIR 

LD 

OR 

SBC 

POSH 

POP 

LD 

CALL 

CALL 
; HL POINTS TO 
DEF035 POP 

LD 

INC 

LD 
DEF040 CALL 

CP 

JP 

LD 

INC 

CALL 

DJNZ 

LD 



HL.(CURCUR) 
(LSTCUR) ,HL 
CLRCOH 
HL.MSG5 
BCLINE13 
DSPMES 
B, 1 

INPUTS 
NZ.DEF050 
B, 1 

DECBIN 
NZ.DEF050 
A,L 

HL.MSG11 
BC, LINE14 
DSPMES 
HL,( LSTCUR) 
(CURCUR) ,HL 
AF 

FNDMSG 
NZ.DEF035 
OR S IN MBUF 
HL 
DE 
HL 
A,(HL) 

M.DEF030 

HL 

DEF025 

HL 

BC 

HL 

HL.ENDM 



HL.BC 
HL 
BC 
HL 

HL.ENDM 
A 

HL.DE 
HL 
BC 

A.OFFH 
FILLCH 
FNDMSG 
MESSAGE AREA, 
AF 

(HL) .A 
HL 
B,0 

INPUTW 
ENTER 
Z.M0R015 
(HL),A 
HL 

DISCHR 
DEF040 
HL, (CURCUR) 



;GET CURRENT CURSOR 
;SAVE 

; CLEAR COMMUNICATIONS AREA 
; DEFINE MESSAGE 
;LINE 13 

;DISPLAY DEFINE MESSAGE 
;1 CHARACTER 
;GET CHARACTER 
;G0 IF GT 1 
:1 CHARACTER 
; CONVERT TO BINARY 
:G0 IF ERROR 
;MSG * NOW IN A 
; INPUT MESSAGE 
;LINE 14 

; DISPLAY MESSAGE 
;GET OLD CURSOR 
; RESTORE 
;SAVE MESSAGE * 
;GET ADDRESS OF MESSAGE 
;G0 IF NO CURRENT MSG FOR I 
MUST DELETE 
;SAVE START 
:PUT IN DE 
;BYPASS * TO TEXT 

;GET CHARACTER 

iTEST FOR NON-ASCII OR -1 

;00 IF NEXT MESSAGE 

;BUMP POINTER 

;C0NTINUE 
;END 



SAVE NEXT AREA 
END OF MEMORY 
CLEAR CARRY 
I OF BYTES TO MOVE 
TRANSFER TO BC 
BYTE COUNT 
RESTORE SOURCE 
MOVE MESSAGE DOWN 
END OF MEMORY 

;FIND I OF BYTES REMAINING 
iTRANSFER TO BC 



-1 

FILL REMAINING WITH -1S 
FIND FIRST -1 
TOP OF STACK HOLDS MESSAGE I 
;GET MESSAGE $ 
;STORE IN MESSAGE AREA 
POINT TO FIRST TEXT CHAR POS 
INITIALIZE COUNT OF CHARS 

;GET NEXT CHARACTER 

;TEST FOR ENTER CHAR 

;G0 IF ENTER 

,-STORE IN MESSAGE AREA 

;BUMP POINTER 

;DISPLAY 

;G0 IF NOT 256 CHARS 
GET CURRENT CURSOR 
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8161 22EB85 


02110 


LD 


(LSTCUR).HL ; 


SA 


VE 


8167 21EB87 


02150 


LD 


HL.MSG12 ; 


"256" CHARACTERS MESSAGE 


816A 01C03F 


02160 


LD 


BC.LINE15 




816D CD6D83 


02170 


CALL 


DSPHES 


DISPLAY WARNING MESSAGE 


8170 21D007 


02180 


LD 


HL.2000 


2000 MILLISECONDS 


8173 CDC085 


02190 


CALL 


DELAY 


DELAY 2 SECS 


8176 2AEB85 


02200 


LD 


HL.(LSTCUR) 


GET OLD CURSOR 


8179 22E985 


02210 


LD 


(CURCUR),HL 


RESTORE 


817C C33780 


02220 


JP 


M0R015 


GET NEXT COMMAND 


817F 21AA87 


02230 DEF050 


LD 


HL.MSG10 


ERROR MESSAGE 


8182 01803F 


02210 


LD 


BC.LINE11 


LINE 11 


8185 CD6D83 


02250 


CALL 


DSPMES 


DISPLAY ERROR MESSAGE 


8188 21D007 


02260 


LD 


HL.2000 


2000 MILLISECONDS 


818B CDC085 


02270 


CALL 


DELAY 


DELAY 2 SECS 


818E C3F180 


02280 


JP 


DEF005 


TRY AGAIN 




02290 ; 

02300 ; «*«»«*«»»"«*«*»«* B SET SPEED R0UTINE* fittt!M,, ** B,,,M,s, * tf s,t,, 




02310 i 








8191 2AE985 


02320 SPEED 


LD 


HL.(CBRCUR) 


GET CURRENT CURSOR 


8191 22EB85 


02330 


LD 


CLSTCHR),HL 


SAVE 


8197 CDFB83 


02310 SPE005 


CALL 


CLRCOH 


CLEAR COMMUNICATION AREA 


819A 21CB86 


02350 


LD 


HL.MSG1 


SPEED MESSAGE 


819D 01103F 


02360 


LD 


BC.LME13 


LINE 13 


81A0 CD6D83 


02370 


CALL 


DSPMES 


DISPLAY SPEED MESSAGE 


81A3 0602 


02380 


LD 


B,2 


2 CHARS 


81A5 CD0D81 


02390 


CALL 


INPUTS 


GET CHARACTER STRING 


81A8 2035 


02100 


JR 


NZ.SPE020 


GO IF GT 2 CHARACTERS 


81AA CD9085 


02110 


CALL 


DECBIN 


CONVERT TO BINARY 


81AD 2030 


02120 


JR 


NZ.SPE020 


GO IF ERROR 


81AF 7D 


02130 


LD 


A,L 


;GET SPEED 0-99 


81B0 FE03 


02110 


CP 


3 


;TEST FOR 3 WPM 


81B2 FADF81 


02150 


JP 


M.SPE020 


;G0 IF LT 3 WPM 


81B5 FE3D 


02160 


CP 


61 


;TEST FOR 60 WPM 


81B7 F2DF81 


02170 


JP 


P.SPE020 


;G0 IF GT 60 WPM 


81BA 21C003 


02180 


LD 


HL.SPEEDF 


;1200/WPM=DOTO TIME 


81BD IF 


02190 


LD 


C, A 


iWPM LS BYTE 


81BE 0600 


02500 


LD 


B,0 


;NOW IN BC 


81C0 11FFFF 


02510 


LD 


DE.-1 


;QUOTIENT 


81 C3 B? 


02520 SPE015 


OR 


A 




ZERO C 


81C1 ED12 


02530 


SBC 


HL.BC 




DIVIDE BY SUCCESSIVE SUB 


81C6 13 


02510 


INC 


DE 




BUMP QUOTIENT 


81C7 30FA 


02550 


JR 


NC.SPE015 




GO IF NOT NEGATIVE 


81C9 ED53E585 


02560 


LD 


(DOTO).DE 


;STORE DOT ON TIME 


81CD 210000 


02570 


LD 


HL,0 




81B0 19 


02580 


ADD 


HL.DE 


:FIND 3"D0T0 


81D1 19 


02590 


ADD 


HL.DE 




81D2 19 


02600 


ADD 


HL.DE 




81D3 22E785 


02610 


LD 


<DASHO),HL 


;STORE DASH ON TIME 


81D6 2AEB85 


02620 


LD 


HL.(LSTCBR) 


;GET OLD CURSOR 


81D9 22E985 


02630 


LD 


(CURCUR).HL 


: RESTORE 


81DC C33780 


02610 


JP 


M0R015 


;BACK TO DRIVER 


81DF 212087 


02650 SPE020 


LD 


HL.MSG6 


; ERROR MESSAGE 


81E2 01803F 


02660 


LD 


BC.LINE11 


;LINE 11 


81E5 CD6D83 


02670 


CALL 


DSPMES 


; DISPLAY ERROR MESSAGE 


81E8 21D007 


026 80 


LD 


HL.2000 


;2000 MILLISCS 


81EB CDC085 


026 90 


CALL 


DELAY 


:DELAY 2 SECS 


81EE 18A7 


02700 
02710 ; 


JR 


SPE005 


;TRY AGAIN 




02720 ;«»«»"»»««»TRANSMIT RANDOM CHARACTERS ROUTINE»«» s *»»»*»» 




02730 i 








81F0 2AE985 


02710 RANDOM 


LD 


HL,(CURCDRj 


iGET CURRENT CURSOR 


81F3 22EB85 


02750 


LD 


(LSTCUR).HL 


:SAVE 


81F6 CDFB83 


02760 


CALL 


CLRCOM 


; CLEAR COMMUNICATION AREA 


81F9 213F87 


02770 


LD 


HL.MSG7 


; RANDOM MESSAGE 


81FC 01103F 


027 80 


LD 


BC.LINE13 


;LINE 13 POSITION 


81FF CB6D83 


02790 


CALL 


DSPMES 


; DISPLAY RANDOM MESSAGE 


8202 ED5F 


02800 


LD 


A,R 


;GET REFRESH COUNT (RANDOM) 


8201 32E185 


02810 


LD 


(SEED+3) ,A 


: INITIAL SEED 


8207 3E20 


02820 


LD 


A, ' ' 


:BLANK 


8209 32EF85 


02830 


LD 


(LASTR) ,A 


; INITIALIZE LAST RANDOM CHAR 


820C 2AEB85 


02810 


LD 


HL.(LSTCUR) 


;GET OLD CURSOR 


820F 22E985 


02850 


LD 


(CURCUR) ,HL 


; RESTORE 


8212 CD1285 


02860 RAN010 


CALL 


RAND 


;GET RANDOM « 0-127 


8215 211288 


02870 


LD 


HL,CTAB 


CHARACTER TABLE 


8218 09 


02880 


ADD 


HL.BC 


; POINT TO CHARACTER 


8219 7E 


02890 


LD 


A,(HL) 


;GET ASCII CHARACTER 


821 A FE20 


02900 


CP 


' ' 


;TEST FOR BLANK 


821C 2008 


02910 


JR 


NZ.RAN020 


;G0 IF NOT BLANK 


82 1E E5 


02920 


PUSH 


HL 




;SAVE HL 



305 



821 F 21EF85 


02930 




LB 


HL.LASTR 


; ADDRESS OF LAST CHAR 


8222 BE 


029*0 




CP 


(HL) 


;TEST AGAINST LAST 


8223 El 


02950 




POP 


HL 


:RESTORE HL 


8221 28EC 


02960 




JR 


Z.RAN010 


;D0N'T SEND 2 BLANKS 


8226 CDBE83 


02970 RAN020 


CALL 


DISCHR 


;DISPLAY CHARACTER 


8229 CD8183 


02980 




CALL 


LPRINT 


;PRINT IF REQ'D 


822C CDE082 


02990 




CALL 


SNDCHR 


;SEND CHAR 


822F 32EF85 


03000 




LD 


(LASTR).A 


:SAVE FOR NEXT COMPARE 


8232 CD2981 


03010 




CALL 


INPUT 


;TEST FOR CLEAR 


8235 18DB 


03020 
03030 
030110 




JR 


RAN010 


;BACK TO NEXT CHAR 




»«B«««»o»»«oii»«iiiANSMIT MESSAGE 


N ROUTINE 8 " * a B fia ff * "* 8 flflfi 




03050 










8237 2AE985 


03060 


SMIT 


LD 


HL,(CURCUR) ; 


GET CURRENT CURSOR 


823A 22EB85 


03070 




LD 


(LSTCUR).HL ; 


SAVE 


823D CDFB83 


03080 




CALL 


CLRCOM ; 


CLEAR COMMUNICATION AREA 


8240 216A87 


03090 




LD 


HL.MSG8 ; 


TRANSMIT MESSAGE 


82*3 C5 


03100 




PUSH 


BC ; 


SAVE MSGS+3*2 


8211 01103F 


031 10 




LD 


BCLINE13 ; 


LINE 13 POSITION 


82*7 OD6D83 


03120 




CALL 


DSPMES ; 


DISPLAY TRANSMIT MESSAGE 




03130 


; MESSAGE i>»2 


STILL IN BC 




821A CI 


03110 




POP 


BC ; 


RETRIEVE MSGJ + 3 ,1 2 


8211 B CB39 


03150 




SRL 


c 


MESSAGE «*3 IN BC 


824D 79 


03160 




LD 


A,C 


MESSAGE *+3 IN A 


821E D603 


03170 




SUB 


3 ; 


MESSAGE J IN A 


8250 CDC782 


03180 




CALL 


FNDMSG 


GET ADDRESS OF MESSAGE 


8253 201E 


03190 




JR 


NZ.XMT020 ; 


GO IF NONE 


8255 23 


03200 




INC 


HL 


BYPASS I 


8256 ED5BEB85 


03210 




LD 


DE.(LSTCUR) 


GET OLD CURSOR 


825A ED53E985 


03220 




LD 


(CURCUR), DE 


RESTORE 


825E 7E 


03230 


XHT010 


LD 


A, (HL) 


;GET NEXT CHARACTER 


825F FE20 


03210 




CP 


' ' 


;TEST FOR NON- ASCII 


826 1 FA3780 


03250 




JP 


M.MOR015 


;G0 IF END OF MESSAGE 


8261 CDBE83 


03260 




CALL 


DISCHR 


iDISPLAY CHARACTER 


8267 CD8183 


03270 




CALL 


LPRINT 


;PRINT IF REQ'D 


826A CDE082 


03280 




CALL 


SNDCHR 


;SEND CHAR 


826D 23 


03290 




INC 


HL 


; POINT TO NEXT 


826E CD2981 


03300 




CALL 


INPUT 


;TEST FOR CLEAR 


8271 18EB 


03310 




JR 


XMTO10 


; CONTINUE SENDING 


8273 219587 


03320 


XMT020 


LD 


HL.MSG9 


ERROR MESSAGE 


8276 01803F 


03330 




LD 


BC.LINE11 


LINE 1* POSITION 


8279 CD6D83 


03310 




CALL 


DSPMES 


DISPLAY ERROR MESSAGE 


827C 21E803 


03350 




LD 


HL.1000 


1000 MILLISECS 


827F CDC085 


03360 




CALL 


DELAY 


DELAY 1 SEC 


8282 2AEB85 


03370 




LD 


HL.(LSTCUR) 


GET OLD CURSOR 


8285 22E985 


03380 




LD 


(CURCUR), HL 


RESTORE 


8288 C33780 


03390 
03100 
03110 




JP 


M0R015 


BACK TO EXECUTIVE 




j 3fi6flaa«»fi90Sfl0fifias«sET PRINT R0UTINE aBa,,s * sfifiBalHIfiflfiBI(I,,, 




03120 


; 








828B 2AE985 


03130 


PRINT 


LD 


HL, (CURCUR) 


GET CURRENT CURSOR 


828E 22EB85 


03*10 




LD 


(LSTCUR).HL 


;SAVE 


8291 3E01 


03*50 




LD 


A, 1 


J PRINT FLAG ON 


8293 32DE85 


03160 




LD 


(PRINTF) ,A 


STORE 


8296 CDFB83 


03170 




CALL 


CLRCOM 


;CLEAR COMMUNICATION AREA 


8299 21B586 


031 80 




LD 


HL.MSG2 


PRINT MESSAGE 


829C 01103F 


03*90 


PRI010 


LD 


BCLINE13 


;LINE 13 


829F CD6D83 


03500 




CALL 


DSPMES 


;DISPLAY PRINT MESSAGE 


82A2 21E803 


03510 




LD 


HL, 1000 


;1000 MILLISECONDS 


82A5 CDC085 


03520 




CALL 


DELAY 


;DELAY 1 SEC 


82A8 2AEB85 


03530 




LD 


HL.(LSTCUR) 


;GET OLD CURSOR 


82AB 22E985 


03510 




LD 


(CURCUR) ,HL 


; RESTORE 


82 AE C33780 


03550 
03560 




JP 


M0R015 


;BACK TO DRIVER 




03570 


• NO PRINT ROUTINE 






03580 


; 








82B1 AF 


03590 


NOPRNT 


XOR 


A 


SPRINT FLAG OFF 


82B2 32DE85 


03600 




LD 


(PRINTF") ,A 


:STORE 


82B5 32BF85 


03610 




LD 


(LPFTF) , A 


; RESET FIRST TIME FLAG 


82B8 2AE985 


03620 




LD 


HL, (CURCUR) 


;GET CURRENT CURSOR 


82BB 22EB85 


03630 




LD 


(LSTCUR).HL 


;SAVE 


82BE CDFB83 


036*0 




CALL 


CLRCOM 


;CLEAR COMMUNICATIONS AREA 


82C1 21BF86 


03650 




LD 


HL.MSG3 


;N0 PRINT MESSAGE 


82C1 C39C82 


03660 
03670 




JP 


PRI010 


;G0 TO DISPLAY, DELAY 




03680 


; »»»a»«»«««8J««o«««»FNDMSG SUBRO 


UTINE fi,,s,lsfi,,as,Mla * ,I,fifi * 81, 




036 90 


;» FINDS MESSAGE BY SCANNING M 


BUF FOR 0-9. 0-9 IS ■• 




03700 


;» MESSAGE 


#. ASCII CHARACTERS 


ARE CHARACTERS TO » 




03710 


;• BE SENT 


-1 IS PADDING AT E 


ND OF MESSAGE. • 



306 



82 C7 
82C8 
82CB 
82CD 
82CE 
82D0 
82D3 
82D4 
82D5 
82D6 
82D7 
82DA 
82DD 
82DF 



C5 

CDD782 

2807 

F5 

3EFF 

CDD782 

F1 

C1 

2B 

C9 

21EA88 

010B0A 

EDB1 

C9 



82E0 F5 
82E1 C5 
82E2 E5 
82E3 DBE5 
82E5 213D88 
82E8 012C00 
82EB EDB9 



82ED 
82EE 
82F0 
82F2 
82F5 
82F7 
82FA 
82FD 
82FE 
82FF 
8300 
8302 
8301) 
8306 
8308 
830A 
830C 
830D 
830F 
8311 
8313 
8315 
8317 
8319 
831C 
831D 
8320 
8321 
8323 
8324 
8325 
8326 



C5 

DDE1 

DB29 

019288 

DD09 

DD6E00 

DD6601 

E5 

El 

7D 

CB3C 

CB1D 

CB3C 

CB1D 

CBFC 

CBF4 

E5 

E603 

2816 

FE01 

2820 

FE02 

28111 

2AE585 

29 

CD5683 

El 

DDE1 

E1 

CI 

F1 

C9 



3327 2AE585 

332A CD3D83 

B32D 2AE585 

8330 CD5683 

3333 18C9 



8335 2AE785 



03720 
03730 
037«0 
03750 
03760 
03770 
037 80 
03790 
03800 
03810 
03820 
03830 
03840 
03850 
03860 
03870 
03880 
03890 
03900 
03910 
03920 
03930 
039110 
03950 
03960 
03970 
03980 
03990 
OHOOO 
04010 
04020 
04 030 
04040 
04050 
04060 
04070 
04080 
04090 
04 100 
041 10 
04120 
04 130 
04140 
04150 
04160 
04 170 
04 180 
04190 
04200 
04 210 
04220 
04230 
04240 
04250 
04 260 
04270 
04280 
04290 
04300 
04310 
04320 
04330 
04340 
04350 
04360 
04370 
04380 
04390 
04400 
04410 
04420 
04430 
04 440 
04450 
04460 
04470 
04480 
04490 
04500 



ENTRY: (A)=MESSAGE t 

EXIT: (HL)=POINTER TO MESSAGE IF Z OR 

POINTER TO NEXT AVAILABLE IF NZ 

RESET 
ALL REGISTERS SAVED EXCEPT HL 



PUSH 

CALL 

JR 

PUSH 

LD 

CALL 

POP 

POP 

DEC 

RET 

LD 

LD 

CPIR 

RET 



BC 

FNDSR 

Z.FND020 

AF 

A.OFFH 

FNDSR 

AF 

BC 

HL 

HL.MBUF 
BC.2571 



;SAVE BC 

;SEARCH 

;G0 IF FOUND 

;SAVE NOT FND FLAG 

;FOR FIRST AVAILABLE 

-.SEARCH 

;GET FLAG 

;RESTORE BC 

; ADJUST HL 

:RETURN 

;START OF MSG BUFFER 

;SIZE OF MBUF 

;COMPARE 

; RETURN 



■ iiiiiiiiiinii SEI D CHARACTER SUBROUTINE""""™"""" 
« SENDS A SINGLE CHARACTER AT CURRENT SPEED BY OUT- « 
« PUTTING A 500 HERTZ TONE TO CASSETTE. « 

« ENTRY.- (AUASCII CHARACTER » 

* ALL REGISTERS SAVED. « 



SNDCHR PUSH 

PUSH 

PUSH 

PUSH 

LD 

LD 

CPDR 
; MUST BE FOUNDI 

PUSH 

POP 

ADD 

LD 

ADD 

LD 

LD 

PUSH 
SND010 POP 

LD 

SRL 

RR 

SRL 

RR 

SET 

SET 

PUSH 

AND 

JR 

CP 

JR 

CP 

JR 

LD 

ADD 

CALL 

POP 

POP 

POP 

POP 

POP 

RET 



AF 

BC 

HL 

IX 

HL.CDTAB+CDTABS- 

BC.CDTABS 



BC 

IX 

IX, IX 

BC.TTAB 

IX, BC 

L.(IX) 

H,(IX+1 ) 

HL 

HL 

A, L 

H 

L 

H 

L 

7.H 

6,H 

HL 

3 

Z,DOT 

1 

Z, DASH 

2 

Z, SPACE 

HL, (DOTO) 

HL,HL 

COFF 

HL 

IX 

HL 

BC 

AF 



DOT HERE 

DOT LD HL.iDOTO) 

CALL CON 

SPACE LD HL.(DOTO) 

CALL COFF 

JR SND010 

DASH HERE 

DASH LD HL.(DASHO) 



;SAVE REGISTERS 



I ; ADDRESS OF CODE TAB END 
SIZE OF CODE TABLE 
SEARCH CODE TABLE 



i INDEX IN HL 
;2«INDEX IN HL 
;TIMING TABLE ADDRESS 
; POINT TO TIMING CHAR 
;GET TIMING CHAR 

;SAVE HL 

;GET CURRENT HL 

;GET NEXT 2 BITS 

i ALIGN FOR NEXT NIBBLE 



:SUBTLETY HERE-TERMINATOR! 
;SAVE CURRENT HL 

;G0 IF DOT 

;DASH= 1 

;G0 IF DASH 

;DOT SPACE=2 

;G0 IF SPACE 
;INTERCHAR SPACE=3 
;2»D0T0+PREVI0US DOTO 
; DELAY 2 DOT TIMES 
; RESET STACK 
;RESTORE REGISTERS 



DOT ON TIME 

TOGGLE CASSETTE OUT 

DOT OFF TIME= DOT ON TIME 

DELAY 

RETURN FOR NEXT NIBBLE 



;DASH ON TIME 



307 



338 


CD3D83 


04510 






CALL 


CON 




TC 


GGLE CASSETTE OUT 


33B 


18F0 


04520 
04530 






JR 


SPACE 


;DASH OFF TIME=D0T OFF TIME 






04540 


ON 


HERE - GENERATE 500 HERTZ TONE 






04550 












33D 


3E01 


04560 CON 




LD 


A, 01 


;ON 


33F 


2B 


04570 






DEC 


HL 


;ADJUST FOR "JR C" 


310 


01FFFF 


04580 






LD 


BC.-1 


; DECREMENT 


3»3 


EE03 


04590 ON010 


XOR 


3 




TOGGLE 


315 


D3FF 


04600 






OUT 


(0FFH),A 




OUTPUT TO CASSETTE LATCH 


347 


E5 


04610 






PUSH 


HL 




SAVE COUNT 


318 


210100 


04620 






LD 


HL,1 




FOR 1 MS 


3tB 


CDC085 


04630 






CALL 


DELAY 




DELAY 1 MS 


34E 


CB2984 


04640 






CALL 


INPUT 




GET POSSIBLE CHARACTER 


351 


E1 


04650 






POP 


HL 




GET COUNT 


352 


09 


04660 






ADD 


HL.BC 




DECREMENT COUNT 


353 


38EE 


04670 






JR 


CONOIO 




GO IF NOT -1 


355 


C9 


04680 
04690 






RET 




;RETURN 






04700 


OFF HERE 










04710 












356 


EE00 


04720 ( 


OFF 




XOR 







358 


2B 


04730 






DEC 


HL 


ADJUST FOR TJR C" 


359 


01FFFF 


04740 






LD 


BC-1 


DECREMENT 


35C 


D3FF 


04750 






OUT 


(0FFH),A 


;0UTPUT TO CASSETTE LATCH 


35E 


E5 


04760 


3FF010 


PUSH 


HL 




SAVE COUNT 


35F 


210100 


04770 






LD 


HL,1 




FOR 1 MS 


362 


CDC085 


04780 






CALL 


DELAY 




DELAY 1 MS 


365 


CD2984 


04790 






CALL 


INPUT 




GET POSSIBLE CHARACTER 


368 


E1 


04 800 






POP 


HL 




GET COUNT 


369 


09 


04810 






ADD 


HL.BC 




DECREMENT COUNT 


36A 


38F2 


04820 






JR 


COFF010 




GO IF NOT -1 


36C 


C9 


04830 
04840 






RET 




;RETURN 






04850 


«e»»««so«««««» DIS pLAJ MESSAGE AT LOCATION N»»«««»«»»««« s 






04860 





DISPLAYS MESSAGE AT GIVEN SCREEN POSITION. TER- » 






04870 


* 


MINATES 


ON NULL (ZERO). 


B 






04880 


s 


ENTRY: 


HL)=MESSAGE LOCATION * 






04890 


fi 






BC)=SCREEN POSITION 


B 






04900 


B 


ALL REGISTERS SAVED. 


S 






04910 












36D 


F5 


04920 


)SPMES 


PUSH 


AP 


SAVE REGISTERS 


36E 


C5 


04930 






PUSH 


BC 




36F 


E5 


04940 






PUSH 


HL 




370 


7E 


04950 


)SP005 


LD 


A,(HL) 




GET MESSAGE CHAR 


371 


B7 


04960 






OR 


A 




TEST FOR 


372 


2809 


04970 






JR 


Z.DSP010 




RETURN IF DONE 


374 


02 


04980 






LD 


(BC) ,A 




STORE CHARACTER 


375 


03 


04990 






INC 


BC 




BUMP SCREEN POINTER 


376 


23 


05000 






INC 


HL 




BUMP MESSAGE POINTER 


377 


ED43E985 


05010 






LD 


(CURCUR).BC 




SAVE POINTER 


37B 


18F3 


05020 






JR 


DSP005 




CONTINUE 


37D 


El 


05030 


5SP010 


POP 


HL 


RESTORE REGISTERS 


)37E 


C1 


05040 






POP 


BC 




i37F 


F1 


05050 






POP 


AF 




380 


C9 


05060 
05070 






RET 




RETURN 






05080 


»B»e3BBSB»BOfiaeofifi«LpR2NT SUBR0UTINE 9sl, B*** fil, ** fie * BfiBsfi * 






05090 


b 


OUTPUTS 


:haracter TO SYSTEM LINE PRINTER IF PRINT « 






05100 


B 


FLAG IS 


SET. 


B 






051 10 


B 


ENTRY: (A)=ASCII CHARACTER 


fi 






05120 


fi 


ALL 


REGISTERS SAVED. 


fi 






05130 












381 


C5 


05140 


.PRINT 


PUSH 


BC 


SAVE REGISTERS 


382 


E5 


05150 






PUSH 


HL 




383 


47 


05160 






LD 


B, A 


SAVE CHARACTER 


384 


3ADE85 


05170 






LD 


A.(PRINTF) 


GET PRINT FLAG 


387 


B7 


05180 






OR 


A 


TEST 


388 


78 


05190 






LD 


A,B 


RESTORE A FOR POSSIBLE RTN 


389 


2821 


05200 






JR 


Z.LPR090 


RETURN IF NOT SET 


38B 


3ADF85 


05210 






LD 


A,(LPFTF) 


GET LINE PRINTER 1ST TIKE 


38E 


B7 


05220 






OR 


A 


TEST 


38F 


2007 


05230 






JR 


NZ.LPR010 


GO IF NOT FIRST TIME 


391 


32E085 


05240 






LD 


(CHARCT) , A 


INITIALIZE CHAR COUNT 


394 


3C 


05250 






INC 


A 


1 TO A 


395 


32DF85 


05260 






LD 


(LPFTF) ,A 


SI 


:t 


FIRST TIME FLAG 



308 



8398 3AE085 
839B E61F 
839D 2005 
839F 3EOD 
83A1 CDAF83 
83A4 78 
83A5 CDAF83 
83A8 21E085 
83AB 34 
83AC El 
83AD C1 
83AE C9 



83AF F5 
83B0 3AE837 
83B3 E6FO 
83B5 FE30 
83B7 20F7 
83B9 F1 
83BA 32E837 
83BD C9 



83BE C5 
83BF E5 
83C0 2AE985 
83C3 77 
83C4 01FF3E 
83C7 23 
83C8 22E985 
83CB B7 
83CC ED42 
83CE 2003 
83D0 CDD683 
83D3 E1 
83D1 C1 
83D5 C9 



83D6 
83D7 
83D8 
83D9 
83DA 
83DD 
83E0 
83E3 
83E5 
83E8 
83EA 
83ED 
83F0 
83F3 
83F6 
83F7 
83F8 
83F9 
83FA 



F5 

C5 

D5 

E5 

11003C 

21403C 

010003 

EDBO 

11C03E 

3E20 

011)000 

CD8385 

21C03E 

22E985 

E1 

D1 

C1 

F1 

C9 



05270 

05280 

05290 

05300 

05310 

05320 

05330 

05310 

05350 

05360 

05370 

05380 

05390 

05100 

05110 

05120 

05430 

05110 

05450 

05160 

05170 

05480 

05190 

05500 

05510 

05520 

05530 

05540 

05550 

05560 

05570 

05580 

05590 

05600 

05610 

05620 

05630 

05640 

05650 

05660 

05670 

056 80 

056 90 

05700 

05710 

05720 

05730 

05740 

05750 

05760 

05770 

05780 

05790 

05800 

05810 

05820 

05830 

05810 

05850 

05860 

05870 

05880 

05890 

05900 

05910 

05920 

05930 

05910 

05950 

05960 

05970 

05980 

05990 

06000 

06010 

06020 

06030 

06040 

06050 



LPR010 LD A.(CHARCT) ;GET CHARACTER COUNT 

;CET 0-31 COUNT 
;G0 IF NOT 32ND 
:CARRIAGE RETURN 
; TEST STATUS AND OUTPUT 
: RESTORE CHARACTER 
;TEST BUSY AND OUTPUT 
; CHARACTER COUNT 
iBUMP CHARACTER COUNT 
; RESTORE REGISTERS 

iRETURN 

LINE PRINTER STATUS AND PRINT CHARACTER SUBROUTINE 



LPR020 



LPR090 



LD 


A.(CHARCT) 


AND 


1FH 


JR 


NZ.LPR020 


LD 


A.ODH 


CALL 


LPSTAT 


LD 


A,B 


CALL 


LPSTAT 


LD 


HL.CHARCT 


INC 


(HL) 


POP 


HL 


POP 


BC 


RET 





LPSTAT PUSH 
LPS010 LD 
AND 
CP 
JR 
POP 
LD 
RET 



Af iSAVE CHAR 
A,(37E8H) ;GET STATUS 

OF0H iMASK OUT GARBAGE BITS 

30H ;TEST FOR BUSY 

NZ.LPS010 jGO IF BUSY 

AF i RESTORE CHAR 

(37E8H),A [OUTPUT 
; RETURN 

; """"""'""""'DISPLAY CHARACTER SUBROUTINE""""""" 
;• OUTPUTS ONE CHARACTER TO CURRENT CURSOR POSITION • 

* ON SCREEN. MOVES CURSOR TO NEXT POSITION UNLESS « 

* LAST CHARACTER POSITION OF LINE 1 1 . IF LATTER • 

* SCROLLS UP FIRST. ' , 
» ENTRY: ( CURCUR ) ^CURRENT CURSOR POSITION » 

* (A)=CHARACTER TO BE OUTPUT • 

* ALL REGISTERS SAVED. ■ 



DISCHR PUSH BC 

PUSH HL 

LD HL.CCURCUR) 

LD (HL),A 

LD BC,3C00H*767 

INC HL 

LD (CURCUR),HL 

OR A 

SBC HL.BC 

JR NZ.DIS010 

CALL SCROLL 

DIS010 POP HL 

POP BC 

RET 

i """"SCROLL SCREEN SUBROUTINE"""""""" 

;« SCROLLS LINES 1-11 UP TO LINES 0-10. FILLS LINE 11 

:» WITH BLANKS. 

;« ENTRY: NO PARAMETERS 

;• ALL REGISTERS SAVED. 



;SAVE REGISTERS 

;GET CHARACTER POSITION 

;ST0RE CHARACTER 

iLAST CP OF LINE 11 

;BUMP CURSOR 

; STORE 

;RESET CARRY 

;TEST FOR LAST 

iRETURN IF NO SCROLL 

iSCROLL UP 

; RESTORE REGISTERS 

iRETURN 



SCROLL 



PUSH 

PUSH 

PUSH 

PUSH 

LD 

LD 

LD 

LDIR 

LD 

LD 

LD 

CALL 

LD 

LD 

POP 

POP 

POP 

POP 

RET 



AF 

BC 

DE 

HL 

DE, SCREEN 

HL.LINE1 

BC, 1024-256 

DE.LINE11 

A, ' ' 

BC.64 

FILLCH 

HL.LINE1 1 

(CURCUR).HL 

HL 

DE 

BC 

AF 



;SAVE REGISTERS 



;START OF SCREEN 

;LINE 1 

i* TO MOVE 

[MOVE EM 

;START OF LINE 11 

;SPACE 

it TO FILL 

;FILL LINE 

;START OF LINE 11 

: RESET 

; RESTORE REGISTERS 



iRETURN 



i """""CLEAR COMMUNICATION AREA SUBROUTINE"""*"" 
!• CLEARS SYSTEM COMMUNICATION AREA > 

;• ENTRY: NO PARAMETERS . 

;• ALL REGISTERS SAVED. i 
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83FB F5 
83FC C5 
83FD D5 
83FE 3E20 
8100 11103F 
81403 01C000 
8H06 CD8385 
8109 B1 
810A CI 
810B F1 
810C C9 



810D 2AE985 

8110 E5 

8111 01 

8112 0E00 
8111 C5 
8115 CDF381 

8118 CI 

8119 FE02 
811B 2809 
811D OC 
811E CDBE83 
8121 10F1 
8123 3EFF 

8125 B7 

8126 El 

8127 11 

8128 C9 



8129 
812A 
812D 
812E 
8131 
8132 
8133 
8136 
8139 
813A 
813C 
813E 
8111 
8112 
8113 
8115 
811-7 
811A 



F5 

3A7F38 

B7 

CAB981 

C5 

E5 

2AED85 

016100 

B7 

EDI 2 

3879 

210138 

7E 

B7 

2007 

CB25 

F21181 

186B 



811C IF 
811D AF 
811E CB3D 

8150 3801 
8152 C608 

8151 18F8 
8156 06FF 

8158 01 

8159 CB39 
815B 30FB 
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06060 
06070 
06080 
06090 
06100 
06 110 
06120 
06130 
06110 
06150 
06160 
06170 
06180 
06190 
06200 
06210 
06220 
06230 
06210 
06250 
06260 
06270 
06280 
06290 
06300 
06310 
06320 
06330 
06310 
06350 
06360 
06370 
06380 
06390 
06100 
06110 
06120 
06130 
06110 
06150 
06160 
06170 
06180 
06190 
06500 
06510 
06520 
06530 
06510 
06550 
06560 
06570 
06580 
06590 
06600 
06610 
06620 
06630 
06610 
06650 
06660 
06670 
06680 
06690 
06700 
06710 
06720 
06730 
06710 
06750 
06760 
06770 
06780 
06790 
06 800 
06810 
06820 
06830 
06810 



PUSH 

PUSH 

PUSH 

LD 

LD 

LB 

CALL 

POP 

POP 

POP 

RET 



AF 

BC 

DE 

A, ' ' 

DE.LINE13 

BC, 192 

FILLCH 

DE 

BC 

AF 



;SAVE REGISTERS 



;BLANK 

;START OF TEXT AREA 
;3 LINES WORTH 
:FILL WITH BLANKS 
; RESTORE REGISTERS 



; RETURN 



aafi«a»a«s«imfl«a XNPUT STRING SUBROUTINE 888888888888888 

• INPUTS STRING OF CHARACTERS AT CURRENT COMMUNICA- 
8 HON AREA. TERMINATED BY ENTER. 

8 ENTRY; (B)=MAXIMUM NUMBER 

• CCURCUR)=CURRENT CURSOR POSITION 
» EXIT; (B)=ACTUAL NUMBER INPUT 

• (HL)=FIRST CHARACTER LOCATION 
« NZ IF GT MAXIMUM NUMBER 

• Z IF LE MAXIMUM NUMBER 

8 ALL R-EGISTERS SAVED EXCEPT HL,BC,A 



INPUTS 



INS030 



LD 

PUSH 

INC 

LD 

PUSH 

CALL 

POP 

CP 

JR 

INC 

CALL 

DJNZ 

LD 

OR 

POP 

LD 

RET 



HL.(CUHCUR) 

HL 

B 

C, 

BC 

INPUTW 

BC 

ENTER 

Z.INS030 

C 

DISCHR 

INS010 

A, OFFH 

A 

HL 

B, C 



CURRENT CURSOR POSITION 

SAVE 

BUMP MAXIMUM 

INITIALIZE COUNT OF CHARS 

SAVE COUNTS 

GET CHARACTER 

RESTORE COUNTS 

TEST FOR DONE 

GO IF ENTER 

BUMP CHARACTER COUNT 

DISPLAY 

GO IF NOT MAXIMUM 
-1 TO A 
RESET Z FLAG 
RETRIEVE START 
GET CHARACTER COUNT 
RETURN 



»0»»»»«»«#«>«»«1CEYBOARD INPUT SUB ROU TINE •••»•«•»«••««« »• 

» IF DEBOUNCE DELAY LESS THAN ELAPSED TIME, SCANS » 

» KEYBOARD AND STORES POSSIBLE INPUT CHARACTER IN » 

• CIRCULAR INPUT BUFFER. » 

» ENTRY: NO PARAMETERS » 

8 EXIT: NO PARAMETERS • 

8 ALL REGISTERS SAVED » 

8 CLEAR CHARACTER CAUSES RESTART AT MOR015H, SP RESET 8 



INPUT PUSH 

LD 

OR 

JP 

PUSH 

PUSH 

LD 

LD 

OR 

SBC 

JR 

LD 
INP010 LD 

OR 

JR 

SLA 

JP 

JR 
; CONVERT ROW, 
INP020 LD 



INP025 



INP035 
INP010 



XOR 

SRL 

JR 

ADD 

JR 

LD 

INC 

SRL 

JR 



AF 

A, C387FH) 
A 

Z, INP065 
BC 
HL 

HL.(TSLC) 
BC.DBDEL 
A 

HL.BC 
C.INP060 
HL.3801H 
A, ( HL} 
A 

NZ.INP020 
L 

P.INP010 
INP060 
COLUMN TO INDEX 
C,A 
A 
L 

CINP035 
A, 8 

INP025 
B, OFFH 



SAVE REGISTERS 

ALL IN ONE SWELL FOOP 

TEST FOR ANY KEY 

GO IF NONE 



:GET TIME SINCE LAST CHARACTER 

;MINIMUM DELAY 

:RESET CARRY 

;COMPARE 

;G0 IF LT DEBOUNCE DELAY 

;ROW ADDRESS 

;GET ROW VALUE 

;TEST FOR NON-ZERO 

;G0 IF INPUT 

;SHIFT ROW ADRESS 

;MORE TO GO 
;RETURN 

;ROW VALUE 
;ZERO A 

;SHIFT ADDRESS 

;G0 IF DONE 

;R0W 8 8 

;C0NTINUE 
; COLUMN COUNT 

;BUMP COUNT 

;SHIFT ROW VALUE 

[CONTINUE UNTIL 1 BIT 



845D 


80 


06850 




ADD 


A,B 


R0W8 + C0L 


8HSE 


4F 


06860 




LD 


C, A 


TRANSFER TO C 






06870 


; FIND 


TABLE ENTRY 




845F 


0600 


06880 




LD 


B, 


NOW IN BC 


8*61 


21BB84 


06890 




LD 


HL, KBTAB 


ADDRESS OF LOOK UP TABLE 


81161) 


09 


06900 




ADD 


HL.BC 


POINT TO VALUE 


8465 


7E 


06910 




LD 


A, (HL) 


GET VALUE 


8466 


B7 


06920 




OR 


A 


TEST CHARCTER 


8467 


284E 


06930 




JR 


Z, INP060 


GO IF NOT VALID 


8469 


F5 


06940 




POSH 


AF 


SAVE CHARACTER 


846A 


3A8038 


06950 




LD 


A, (3880H) 


GET SHIFT 


8I46D 


OF 


06 960 




RRCA 




ALIGN TO BIT 7 


816 E 


47 


06970 




LD 


B, A 


PUT IN B 


846 F 


F1 


06980 




POP 


AF 


RESTORE CHARACTER 


8470 


FE2F 


06990 




CP 


' / ' 


TEST FOR SLASH 


8472 


2804 


07000 




JR 


Z, INP052 


GO IF SLASH 


8474 


FE2D 


07010 




CP 


'- ' 


TEST FOR MINUS 


8476 


2006 


07020 




JR 


NZ.INP055 


NEITHER 


8478 


CB7 8 


07030 


INP052 


BIT 


7,B 


TEST FOR SHIFT 


847A 


2802 


07040 




JR 


Z.INP055 


GO IF LOWER CASE 


847C 


CBE7 


07050 




SET 


4 ,A 


/ TO ? OR - TO = 


847E 


FE01 


07060 


INP055 


CP 


CLEAR 


TEST FOR CLEAR 


8480 


2018 


07070 




JR 


NZ.INP057 


GO IF NOT CLEAR 


8482 


315994 


07080 




LD 


SP.TOPS 


RESET STACK, DROP REGS 


8485 


2AE985 


07090 




LD 


HL,(CURCUR j 


GET LAST CURSOR POSN 


8488 


01403F 


07100 




LD 


BC, LINE13 


START OF COHM AREA 


848B 


B7 


071 10 




OR 


A 


CLEAR CARRY 


848C 


ED42 


07120 




SBC 


HL.BC 


COMPARE 


848E 


FA9784 


07130 




JP 


M, INP056 


GO IF IN TEXT AREA 


8491 


2AEB85 


07140 




LD 


HL.(LSTCUR) 


GET TEXT AREA PUTR 


8494 


22E985 


07150 




LD 


(CURCUR) , HL 


RESET CURSOR POSN 


8497 


C337 80 


07160 


INP056 


JP 


M0R0 15 


RETURN TO EXEC 






07170 


; STOBE 


CHARACTER IN CIRCULAR INI 


UT BUFFER 


849A 


2AF285 


07180 


INP057 


LD 


HL.(IBUFN) 


GET POINTER TO NEXT 


849D 


BO 


07190 




OR 


B 


MERGE IN SHIFT BIT 


849E 


77 


07200 




LD 


(HL) ,A 


STORE THIS CHARACTER 


849F 


23 


07210 




INC 


HL 


BUMP TO NEXT SLOT 


84A0 


22F285 


07220 




LD 


(IBUFN) ,HL 


STOHE 


84A3 


01F593 


07230 




LD 


BC, IBUFE 


END OF INPUT BUFFER 


84A6 


B7 


07240 




OR 


A 


RESET CARRY 


84A7 


ED4 2 


07250 




SBC 


HL.BC 


TEST FOR END 


84A9 


2006 


07260 




JR 


NZ.INP059 


GO IF NOT END 


84 AB 


21F592 


07 270 




LD 


HL.IBUF 


START OF I BUFFER 


84AE 


22F285 


07280 




LD 


(IBUFN) ,HL 


BACK TO BEGINNING 


84B1 


210000 


07290 


INP059 


LD 


HL.O 


ZERO HL 


84B4 


22ED85 


07300 




LD 


(TSLC).HL 


RESET TIMER 


84 B7 


El 


07310 


INP060 


POP 


HL 


RESTORE REGISTERS 


84B8 


CI 


07320 




POP 


BC 




84B9 


F1 


07330 


INP065 


POP 


AF 




84BA 


C9 


07340 
07350 




RET 




RETURN 






07360 


i KEYBOARD LOOK 


UP TABLE HERE FO 


1 LOWER CASE 






07370 


; 








84 BB 


00 


07380 


KBTAB 


DEFB 


0- 


;ROW - § 


84BC 


41 

42 43 44 


07390 
45 46 


47 


DEFM 


1 ABCDEFG ' 




84 C3 


48 

49 4A 4B 


07400 
4C 4D 


4E 4F 


DEFM 


'HIJKLMNO' 


;ROW 1 


84CB 


50 

51 52 53 


07410 
54 55 


56 57 


DEFM 


' PQRSTUVW' 


;R0W 2 


84D3 


58 
59 5A 


07420 




DEFM 


>XYZ ' 


;ROW 3 


84 D6 


00 


07430 




DEFB 







84 D7 


00 


07440 




DEFB 







84D8 


00 


07450 




DEFB 







84D9 


00 


07460 




DEFB 







84DA 


00 


07470 




DEFB 







84DB 


30 

31 32 33 


07480 
34 35 


36 37 


DEFM 


'01234567 ' 


;ROW 4 


84E3 


38 
39 
00 


07490 




DEFM 


■89* 


;ROW 5 


84E5 


07500 




DEFB 





; COLON 


84E6 


3B 


07510 




DEFB 


t . t 


; "ERROR" 


84 E7 


2C 

2D 2E 2F 


07520 




DEFM 


1 '•-■' • 




84EB 


02 


07530 




DEFB 


2 


:ROW 6 - ENTER 


84EC 


01 


07540 




DEFB 


1 


; CLEAR 


84ED 


00 


07550 




DEFB 





;BREAK 


84EE 


00 


07560 




DEFB 





;UP ARROW 
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84EF 


00 


07570 




DEFB 





;D0HN ARROW 




84 FO 


00 


07580 




DEFB 





;LFT ARROW 




84F1 


00 


07590 




DEFB 





;RT ARROW 




81F2 


20 


07600 
07610 




DEFM 












07620 


;«»»»• BSfifi« INPUT CHARACTER AND 


WAIT SUBROUTINE"""""" 






07630 


• B 


INPUTS SINGLE CHARACTER FROM KEYBOARD BY WAITING 


9 






07640 


fi 


UNTIL CHARACTER PRESENT. 




B 






07650 


fi 


ENTRY: NO 


PARAMETERS 




S 






07660 


e 


EXIT: (A 


^CHARACTER 




B 






07670 


fi 


ALL REGISTERS SAVED EXCEPT 


A 


fi 






076 80 












84F3 


E5 


076 90 


[NPUTW push 


HL 


;SAVE REGISTERS 




84F4 


216500 


07700 




LD 


HL.DBDELP 


: MINIMUM DELAY+1 




814 F? 


CDC085 


07710 




CALL 


DELAY 


! AVOID PREVIOUS CHAR 




84FA 


216500 


07720 




LD 


HL,DBDELP 


i MINIMUM DELAY ♦ 1 




84FD 


22ED85 


07730 




LD 


(TSLC) ,HL 


; INITIALIZE 




8500 


21F592 


07740 




LD 


HL.IBUF 


;START OF INPUT BUFFER 




8503 


22F285 


07750 




LD 


(IBUFN).HL 


;RESET NEXT CHAR SLOT 


PNTR 


8506 


22F085 


07760 




LD 


(IBUFD.HL 


;RESET LAST CHARACTER 


SLOT 


8509 


CD2981 


07770 


INW010 CALL 


INPUT 


:SCAN 




850C 


05 


07780 




PUSH 


BC 






850D 


CD1585 


07790 




CALL 


GETCHR 


;GET POSSIBLE CHARACTER 


8510 


C1 


07 80 




POP 


BC 






8511 


28F6 


07810 




JR 


Z.INW010 


;G0 IF NOTHING 




8513 


E1 


07820 




POP 


HL 


; RESTORE REGISTERS 




8511 


C9 


07830 
07840 




RET 




; RETURN 








07 850 


»»»««»«»8«»»»»»GET CHARACTER SUBROUTINE""""""""" 






07860 


it 


GETS CHARACTER FROM INPUT 


BUFFER IF THERE IS ONE 


b 






07 870 


fi 


ENTRY: NO 


PARAMETERS 




B 






07 880 


B 


EXIT: (A)= 


ASCII CHARACTER 


OR ZEROES IF NONE 


B 






07890 


B 


Z IF NONE, NZ IF CHARACTER 


fi 






07 900 


B 


(B) = 


80H IF SHIFT, 


IF NO SHIFT 


fi 






07910 


B 


ALL REGISTERS SAVED EXCEPT 


A,BC 


B 






07920 












8515 


E5 


07930 


3ETCHR PUSH 


HL 


;SAVE REGISTERS 




8516 


2AF085 


07940 




LD 


HL.(IBUFL) 


;LAST CHARACTER 




8519 


ED4BF285 


07950 




LD 


BC.(IBUFN) 


;NEXT SLOT 




851D 


B7 


07960 




OS 


A 


[RESET CARRY 




851E 


ED4 2 


07970 




SBC 


HL.BC 


;TEST FOR END 




8520 


28 IE 


07980 




JR 


Z.GET070 


;G0 IF CAUGHT UP 




8522 


09 


07990 




ADD 


HL.BC 


;RESTORE IBUFL 




8523 


7E 


08000 




LD 


A,(HL) 


;GET NEXT CHARACTER 




8521 


E680 


08010 




AND 


80H 


;MASK IN SHIFT 




8526 


47 


08020 




LD 


B,A 


;B NOW HAS SHIFT BIT 




852T 


7E 


08030 




LD 


A,(HL) 


iNEXT CHARACTER 




8528 


E67F 


08040 




AND 


7FH 


:A NOW HAS CHARACTER 




8524 


C5 


08050 




PUSH 


BC 


;SAVE SHIFT 




852B 


F5 


08060 




PUSH 


AF 


iSAVE CHARACTER 




852C 


23 


08070 




INC 


HL 


;BUMP LAST PNTR 




852D 


22F085 


08080 




LD 


(IBUFD.HL 


[SAVE 




8530 


01F593 


08090 




LD 


BCIBUFE 


;END OF I BUF 




8533 


B7 


08100 




OR 


A 


:RESET CARRY 




8531 


ED4 2 


08110 




SBC 


HL,BC 


;TEST FOR END 




8536 


2006 


08120 




JR 


NZ.GET065 


;G0 IF NOT END 




8538 


21F592 


08130 




LD 


HL.IBUF 


i START OF I BUF 




853B 


22F085 


08140 




LD 


(IBUFD.HL 


;BACK TO BEGINNING 




853E 


F1 


08150 C 


ET065 POP 


AF 


;RESTORE CHARACTER 




853F 


C1 


08160 




POP 


BC 


;RESTORE SHIFT 




8510 


E1 


08170 C 


ET070 POP 


HL 


; RESTORE ENTRY REGISTER 


8511 


C9 


08180 
08190 




RET 




; RETURN 








08200 


»B8imimmiifjj||D0(i NUMBER 


ROUTINE""""BBBBSBBBBB 






08210 ; 


B 


GENERATES 


A PSEUDO-RANDOM 


# FROM TO 127. 


fi 






08220 ; 


B 


ENTRY: NO 


PARAMETERS 




3 






08230 ; 


B 


EXIT: (BC)=RANDOM # 0-127 




fi 






08240 ; 


B 


ALL REGISTERS SAVED EXCEPT 


BC. 


B 






08250 , 












8542 


F5 


08260 F 


AND 


PUSH 


AF 


;SAVE REGISTERS 




8543 


D5 


08270 




PUSH 


DE 






8541 


E5 


08280 




PUSH 


HL 






8545 


ED5BE185 


08290 




LD 


DE.(SEED) 


;GET SEED 




8549 


2AE385 


08300 




LD 


HL,(SEED+2) 






854C 


0607 


08310 




LD 


B.7 


;COUNT FOR MULTIPLY BY 


128 


854E 


CD6B85 


08320 E 


DM010 CALL 


SHIFT 


;SHIFT ONE BIT LEFT 




8551 


10FB 


08330 




DJNZ 


RDM010 


;SEED»128 
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8553 0603 
8555 CD7185 
8558 10FB 
855A ED53E185 
855E 22E385 
8561 3ETF 
8563 A2 
8561 IF 
8565 0600 
856T E1 

8568 D1 

8569 F1 
856A C9 



856B 29 
856C EB 
856D ED6A 
856F EB 
8570 C9 



8571 C5 

8572 ED1BE385 

8576 B7 

8577 ED12 

8579 EB 

857A ED1BE185 
857E ED12 

8580 EB 

8581 C1 

8582 C9 



8583 12 
85814 13 

8585 OB 

8586 F5 

8587 78 

8588 B1 

8589 2803 
858B F1 
858C 18F5 
858E F1 
858F C9 



8590 C5 

8591 D5 

8592 DDE5 
8591 DD210000 
8598 DD29 
859A DDE5 
859C DD29 



08310 
08350 
08360 
08370 
08380 
08390 
08100 
08110 
08120 
08130 
08110 
08150 
08160 
08170 
08180 
08190 
08500 
08510 
08520 
08530 
08510 
08550 
08560 
08570 
08580 
08590 
08600 
08610 
08620 
08630 
08610 
08650 
08660 
08670 
08680 
08690 
08700 
08710 
08720 
08730 
08710 
08750 
08760 
08770 
08780 
08790 
08800 
08810 
08820 
08830 
08810 
08850 
08860 
08870 
08880 
08890 
08900 
08910 
08920 
08930 
08910 
08950 
08960 
08970 
08980 
08990 
09000 
09010 
09020 
O9O30 
09010 
09050 
09060 
09070 
09080 
09090 
09100 
091 10 
09120 



LD 

CALL 

DJNZ 

LD 

LD 

LD 

AND 

LD 

LD 

POP 

POP 

POP 

RET 



B.3 

SUB 

RDM020 

(SEED) ,DE 

(SEED+2),HL 

A.7FH 

D 

C,A 

B,0 

HL 

DE 

AF 



iFOR SUBTRACT 

;SUBTRACT ONE 

;SEED»128-3»SEED=SEED«125 
;STORE NEW SEED 

iMASK 

;GET 0-127 
;N0W IN C 
;N0W IN BC 
;REST0RE REGISTERS 



;SHIFT HL 



iilfffli 



ADD 


HL.HL 


EX 


DE,HL 


ADC 


HL.HL 


EX 


DE.HL 


RET 





B«a«»»**t«SHIFT SUBROUTINE""""*""""" 
SHIFTS CONTENTS OF (DE.HL) ONE BIT LEFT 
ENTRY: NUMBER TO BE SHIFTED IN (DE.HL) 
EXIT: (DE.HL) SHIFTED LEFT ONE BIT, LOGICAL 
ALL REGISTERS SAVED EXCEPT DE.HL. 



;SHIFT HL 

;GET MS BYTE 

;SHIFT MS 2 BYTES AND CARRY 

;NOW 0RIGINAL»2 

iRETURN 

jBiinnisniimisijsjfijjcj SEED SUBROUTINE"*""""*"" 
;• SUBTRACTS FOUR BYTES OF SEED FROM (DE.HL). » 

;• ENTRY: (SEED - SEED+3) =SEED * » 

;' (DE.HL)rFOUR-BYTE VALUE « 

;» EXIT: (DE,HL)=RESULT OF SUBTRACT » 

;• ALL REGISTERS SAVED EXCEPT DE.HL » 

SUB PUSH BC ;SAVE REGISTERS 

:GET LS BYTE 
; RESET CARRY 
iSUBTRACT LS 2 BYTES 
;GET MS 2 BYTES 
;GET MS 2 BYTES 
; SUBTRACT MS 2 BYTES AND CY 
;N0W ORIGINAL-SEED 
;RESTORE REGISTERS 
iRETURN 

• •>!•••••>• •••••fii.l CHARACTER SUB ROUTINE*""" • *«" ••» 

» FILLS DESIGNATED AREA WITH GIVEN CHARACTER * 

» ENTRY: t A)=CHARACTEH • 

« (DE)=AHEA « 

• (BCUNUMBER OF BYTES, 1-65525; IS 65536 « 
« ALL REGISTERS SAVED EXCEPT BC.DE « 



PUSH 


BC 




LD 


BC 


(SEED+2) 


OR 


A 




SBC 


HL 


BC 


EX 


DE 


HL 


LD 


BC 


(SEED) 


SBC 


HL 


BC 


EX 


DE 


HL 


POP 


BC 




RET 







LD 

INC 

DEC 

PUSH 

LD 

OR 

JR 

POP 

JR 

POP 

RET 



(DE) ,A 

DE 

BC 

AF 

A,B 

C 

Z.FIL010 

AF 

FILLCH 

AF 



;FILL CHARACTER 
iBUMP POINTER 
; DECREMENT COUNT 
;SAVE FILL CHAR 
;TEST FOR ZERO 

;G0 IF DONE 

;REST0RE FILL CHAR 

iCONTINUE 
; RESTORE A 
[RETURN 



• "•""DECIMAL TO BINARY CONVERSION SUBROUTINE""""" 
« CONVERTS UP TO SIX ASCII CHARACTERS REPRESENTING • 
» DECIMAL NUMBER TO BINARY. MAXIMUM VALUE IS 65535. • 
» ENTRY: (HL)=BUFFER CONTAINING ASCII • 

* (B)=NUMBER OF CHARACTERS » 
» EXIT: (HL)=BINARY S 0-65535 » 
« NZ IF INVALID ASCII CHARACTER OTHERWISE Z » 
» ALL REGISTERS SAVED EXCEPT A,HL « 



DECBIN 



PUSH 

PUSH 

PUSH 

LD 

ADD 

PUSH 

ADD 



BC 
DE 
IX 

IX, 
IX, IX 
IX 
IX, IX 



:SAVE REGISTERS 



;SET RESULT 

;INTERMEDIATE»2 



;*1 
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859E 
85A0 
85A1 
85A3 
85A4 
85A6 
85A9 
85AB 
85AE 
85AF 
85B1 
85B3 
85B4 
85B6 
85B7 
85B8 
85BA 
85 BB 
85BD 
85BE 
85BF 



85C0 
85C1 
85C2 
85C3 
85C6 
85 C7 
85C9 
85CB 
85CC 
85CF 
85D0 
85D3 
85D4 
85D5 
85D8 
85D9 
85DA 
85DB 



85DC 
85DE 
85DF 
85E0 
85E! 
85E3 
85E5 
85E7 
85E9 
85EB 
85ED 
85EF 
85F0 
85F2 



85F4 



DD29 

D1 

DD19 

7E 

D630 

FAB685 

FEOA 

F2B685 

5F 

1600 

DD19 

23 

10E2 

78 

B7 

DDE5 

E1 

DDE1 

D1 

CI 

C9 



C5 

D5 

E5 

11FFFF 

2B 

0682 

10FE 

E5 

2AED85 

23 

22ED85 

El 

19 

DAC785 

El 

D1 

C1 

C9 



0000 

00 

00 

00 

D204 

2E16 

9001 

B004 

003C 

003C 

0000 

20 

F592 

F592 



20 

20 20 20 

20 20 20 

20 20 20 

20 20 20 

52 47 2A 

20 20 20 

20 20 20 

20 20 20 



8631 



111 



20 43 
45 52 



09130 
09140 
09150 
09160 
09170 
09180 
09190 
09200 
09210 
09220 
09230 
09240 
09250 
09260 
09270 
09280 
09290 
09300 
09310 
09320 
09330 
09340 
09350 
09360 
09370 
09380 
09390 
09400 
09410 
09420 
09430 
09440 
09450 
09460 
09470 
09480 
09490 
09500 
09510 
09520 
09530 
09540 
09550 
09560 
09570 
09580 
09590 
09600 
09610 
09620 
09630 
09640 
09650 
09660 
09670 
09680 
09690 
09700 
09710 
09720 
09730 
09740 
09750 
09760 
09770 
09780 
09790 
20 20 
20 20 
20 20 
2A 2A 
2A 2A 
20 20 
20 20 
20 20 
09800 
3D 53 
41 52 
20 53 



ADD 

POP 

ADD 

LD 

SUB 

JP 

CP 

JP 

LD 

LD 

ADD 

INC 

DJNZ 

LD 

OB 

PUSH 

POP 

POP 

POP 

POP 

RET 



IX, IX 

DE 

IX, DE 

A,(HL) 

30H 

H.DEC070 

10 

P.DEC070 

E,A 

D,0 

IX, DE 

HL 

DEC040 

A,B 

A 

IX 

HL 

IX 

DE 

BC 



•8 

•2 

»10 

GET CHARACTEB 

CONVERT 

GO IF LT "0" 

TEST FOR GT "9" 

GO IF GT "9" 

NOW IN E 

NOW IN DE 

MEBGE 



;G0 IF MORE 
:COUNT TO A 
;SET OR RESET Z FLAG 
;RESULT TO HL 

;RESTORE REGISTERS 



iRETURN 



aBaaaBBaaaaaaeafiaaDELAY subroutine 9999999999999999999999 
a DELAYS 1 TO 65536 MILLISECONDS. ' 

» ENTRY: (HL)=DELAY COUNT IN MILLISECONDS « 

« 0=65536 " 

9 ALL REGISTERS SAVED. " 



DELAY 



DEL010 
DEL020 



PUSH 

PUSH 

PUSH 

LD 

DEC 

LD 

DJNZ 

PUSH 

LD 

INC 

LD 

POP 

ADD 

JP 

POP 

POP 

POP 

RET 



BC 

DE 

HL 

DE,-1 

HL 

B, 130 

DEL020 

HL 

HL,(TSLC) 

HL 

(TSLO.HL 

HL 

HL.DE 

CDEL010 

HL 

DE 

BC 



iSAVE REGISTERS 



i-1 FOR DECREMENT 
;ADJUST FOR "JP NC" 

; INNER LOOP TIMING 

;L00P FOR 1 MILLISEC 

;SAVE COUNT 

;GET TIMER COUNT 

;BUMP 

;SAVE 

; RESTORE OUTER LOOP CNT 

; DECREMENT OUTER LOOP CNT 

;C0NTINUE 
;REST0RE REGISTERS 



BBaasaaaaaaaBBfiaaBBtyQRKjtyG ST0RAG£ EI ' >9>,<i(li,felelfelfil 



TMP1 

PRINTF 

LPFTF 

CHARCT 

SEED 

DOTO 

DASHO 

CURCUR 

LSTCUR 

TSLC 

LASTR 

IBUFL 

IBUFN 



DEFW 
DEFB 
DEFB 
DEFB 
DEFW 
DEFW 
DEFW 
DEFW 
DEFW 
DEFW 
DEFW 
DEFB 
DEFW 
DEFW 











1234 

5678 

400 

1200 

3C00H 

3C00H 



1 ! 

IBUF 
IBUF 



;TEMP0RARY STORAGE 
;PRINTER FLAG:0=0FF, 1=ON 
;LP 1ST TIME FLAG:0=1ST TIME 
;LP CHARACTER COUNTER 
;DEFAULT SEED 

;DOT ON TIME (3 WPM DEFAULT) 
;DASH ON TIME (3 WPM DEFLT) 
;CURRENT CURSOR POSITION 
;LAST CURSOR POSITION 
;TIME IN MS SINCE LAST CHAR 
;LAST RANDOM CHARACTER SENT 
; POINTER TO LAST IBUF SLOT 
^POINTER TO NEXT IBUF SLOT 



; BSBBBaaaeaafiBBaasBafisYSTEM MESSAGES 999999999999999999999 



MSG1 D 
20 20 20 
20 20 20 
20 20 20 
2A 4D 4F 
20 20 20 
20 20 20 
20 20 20 
20 20 

D 
45 4E 44 



»» 9 MORG 999 



'CHAR=SEND CHARACTER SHIFT 0-9=SEND MSG N' 



43 54 
49 46 
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51 20 30 2D 39 3D 53 15 
HE 11 20 ID 53 17 20 HE 



865D 20 09810 DEFM 

20 53 18 19 16 51 20 52 
3D 53 15 IE 11 20 52 11 
IE 11 IF ID 20 20 53 18 

19 16 51 20 11 3D 11 15 
16 19 IE 15 20 ID 53 

8685 17 09820 DEFM 

20 20 20 53 18 19 16 51 
20 53 3D 11 15 16 19 IE 
15 20 53 50 15 15 11 20 
20 53 18 19 16 51 20 50 
2C IE 3D 50 52 19 IE 51 



SHIFT R=SEND RANDOM SHIFT D=DEFINE MS' 



'G SHIFT SiDEFINE SPEED SHIFT P,N=PRINT' 



86AE 20 09830 DEFM 

IF 52 20 IE IF 
86B1 00 09810 DEFB 

86B5 50 09850 MSG2 

52 19 IE 51 20 53 15 51 



86BE 00 09860 

86BF 50 09870 MSG3 

52 19 IE 51 20 52 15 53 
15 51 
86CA 00 09880 

86CB 53 09890 MSG1 

15 51 20 53 50 15 15 11 

20 ID IF 11 15 2E 20 15 

IE 51 15 52 20 53 50 15 

15 11 20 33 20 51 IF 20 

36 30 20 57 50 ID 3A 20 



DEFM 


'PRINT SET' 


DEFB 
DEFM 




'PRINT RESET 


DEFB 
DEFM 




•SET SPEED Mi 



SET SPEED MODE. ENTER SPEED 3 TO 60 WPM: 



■ 6F1 


00 






09900 




DEFB 


6F5 


11 






0991 


MSG5 


DEFM 




15 


16 


19 


IE 15 


20 ID 


15 




53 


53 


11 


17 15 


20 ID 


IF 




11 


15 


2E 


20 15 


IE 51 


15 




52 


20 


ID 


15 53 


53 11 


17 




15 


20 


23 


20 30 


2D 39 


3A 




20 












I71F 


00 






09920 




DEFB 


I720 


19 






09930 


MSG6 


DEFM 




IE 


56 


11 


1C 19 


11 20 


53 




50 


15 


15 


11 2E 


20 ID 


55 




53 


51 


20 


12 15 


20 33 


20 




51 


IF 


20 


36 30 






!73E 


00 






09910 




DEFB 


I73F 


52 






09950 


MSG7 


DEFM 




11 


IE 


11 


IF ID 


20 13 


18 




11 


52 


1(1 


13 51 


15 52 


20 




ID 


IF 


11 


15 2E 


20 50 


52 




15 


53 


53 


20 13 


1C 15 


11 




52 


20 


51 


IF 20 


53 51 


IF 




50 












3769 


00 






09960 




DEFB 


S76A 


51 






09970 


MSG8 


DEFM 




52 


11 


IE 


53 ID 


19 51 


20 




ID 


15 


53 


53 11 


17 15 


20 




ID 


IF 


11 


15 2E 


20 50 


52 




15 


53 


53 


20 13 


1C 15 


11 




52 


20 


51 


IF 20 


53 51 


IF 




50 












3791 


00 






09980 




DEFB 


3795 


IE 






09990 


MSG9 


DEFM 




IF 


20 


ID 


15 53 


53 11 


17 




15 


20 


12 


59 20 


51 18 


11 




51 


20 


23 








37A9 


00 






10000 




DEFB 


B7AA 


19 






10010 


MSG10 


DEFM 




IE 


56 


11 


4C 19 


11 20 


ID 




15 


53 


53 


11 17 


15 20 


23 




2E 


20 


ID 


55 53 


51 20 


12 




15 


20 


30 


2D 39 






87C8 


00 






10020 




DEFB 


87C9 


15 






10030 


MSG1 1 


DEFM 




IE 


51 


15 


52 20 


ID 15 


53 




53 


11- 


17 


15 2E 


20 51 


15 



'DEFINE MESSAGE MODE. ENTER MESSAGE # 0-9: 



•INVALID SPEED. MUST BE 3 TO 60 ' 



'RANDOM CHARACTER MODE. PRESS CLEAR TO STOP' 



'TRANSMIT MESSAGE MODE. PRESS CLEAR TO STOP' 



•NO MESSAGE BY THAT ♦• 



'INVALID MESSAGE S. MUST BE 0-9' 



'ENTER MESSAGE. TERMINATE BY ENTER' 
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52 ID 49 «E 11 54 15 20 
12 59 20 15 IE 54 45 52 



87EA 00 

87EB 4D 

IF 52 
20 32 
52 11 
20 32 
15 50 

8811 00 



8812 41 

12 43 
4A 4B 

52 53 
5A 30 
37 38 
20 3D 

883E 30 

31 32 
39 2E 
3B 41 
48 49 
50 51 
58 59 

886A 20 

20 20 
20 20 
20 

887C 11 

42 43 
1A IB 

53 54 



8812 
002C 



8892 3400 
8894 0103 
8896 1103 
8898 C100 
889A 0C00 
889C 1003 
889E C500 
88A0 0003 
88A2 3000 
88A1 5103 
88A6 D100 
88A8 0103 
88AA 3500 
88AC 3100 
88AE D500 
88BO 1403 
88B2 4503 
88B4 C400 
88B6 COOO 
88B8 ODOO 
88BA DOOO 
88BC 4003 
88BE D400 
88C0 4103 



10040 

10050 MSG12 
45 20 54 48 11 
35 36 
13 54 



DEFB 
DEEM 



'MORE THAN 256 CHARACTERS. 256 ACCEPTED' 



4E 
41 
2E 
35 36 20 41 43 43 



20 43 48 
45 52 53 



45 44 
10060 
10070 
10080 
10090 ;» 
10100 ;* 
10110 ; » 
10120 :• 
10130 ; 
10140 CTAB 
45 46 47 1 



DEFB 

; easBaesafisaaaaaaaacTAB CHARACTER TABLE 90 * 9 9 aaaa a * aaeaaaa 
;» TABLE OF CHARACTERS TO BE SENT IN RANDOM MODE. • 
;« DISTRIBUTION DOES NOT CORRESPOND TO THAT IN NOR- • 
;» MAL TEXT. SPACE CHARACTER N0MINALL1 EVERY 5TH » 
;» CHARACTER. * 



DEFM 



49 



4C ID 4E 4F 50 51 



55 56 57 58 59 
32 33 34 35 36 



39 2E 2C 3F 2F 2D 
3B 

10150 D 

33 34 35 36 37 38 
2C 3F 2F 2D 20 3D 
42 13 44 45 46 47 
1A 4B 4C 'ID IE 4F 
52 53 54 
5A 

10160 D 

20 20 20 20 20 20 
20 20 20 20 20 20 



'ABCDEFGHIJKLMN0PQRSTUVWXYZ01234 56 789. ,?/- 



'01234 56 789. ,7/- = ; ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 



55 56 57 



10170 
44 45 46 
4C ID IE 
55 56 59 
10180 
10190 
10200 
10210 
10220 
10230 
10240 
10250 
10260 
10270 
10280 
10290 
10300 
10310 
10320 
10330 
10340 
10350 
10360 
10370 
10380 
10390 
10400 
10410 
10420 
10430 
10440 
10450 
10460 
10470 
10180 
10190 
10500 
10510 
10520 
10530 
10510 
10550 
10560 



'ABCDEFGHIJKLMNOPRSTUVY' 



17 48 49 
4F 50 52 



aaaaaaaaaaaaaaaeaaacDTAB CODE TABLE 9aaaaaa9aaliaa9a9aa9aa 
9 TABLE OF VALID ASCII CHARACTERS TO BE TRANSMITTED. a 
9 INDEX TO CHARACTER USED TO OBTAIN TIMING CODES a 
a FROM TTAB. a 



CDTAB 
CDTABS 



EQU 
EQU 



CTAB 
44 



;SAME DATA 
[SIZE OF DATA 



; aaaaaaaaaaaaasaaaaaxxAB TIMING TABLE aaaaaa999aaa99aaaaaa 
: a TABLE OF TIMING CODES FOR CHARACTERS IN CDTAB. 9 
; a POSITION IN THIS TABLE CORRESPONDS TO POSITION IN a 
; a CDTAB. EACH ENTRY IS 2 BYTES LONG. 9 

■aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaagaaaaaaaaaaaaaaaaaaaaaaaa 



TTAB 



DEFW 


34 H 


DEFM 


30 1H 


DEFW 


311H 


DEFW 


0C1H 


DEFW 


OCH 


DEFW 


310H 


DEFW 


0C5H 


DEFW 


300H 


DEFW 


30H 


DEFW 


354H 


DEFW 


0D1H 


DEFW 


301H 


DEFW 


35H 


DEFW 


31H 


DEFW 


0D5H 


DEFW 


314H 


DEFW 


345H 


DEFW 


0C4H 


DEFW 


OCOH 


DEFW 


ODH 


DEFW 


ODOH 


DEFW 


34 OH 


DEFW 


0D4H 


DEFW 


34 1H 
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88C2 5103 
88C1 0503 
88C6 550D 
88C8 510D 
88CA 500D 
88CC ItOOD 
88CE OOOD 
88D0 OOOC 
88D2 010C 
88D1 050C 
88D6 150C 
88D8 550C 
88DA 4131 
88DC 0535 
88DE 5030 
88E0 H10C 
88E2 0131 
88E1 AA03 
88E6 HOC 
88E8 0000 



88EA 
92F5 



92F5 
93F5 
9159 
8000 
00000 TOTAL 



10570 
10580 
10590 
10600 
10610 
10620 
10630 
10610 
10650 
10660 
10670 
106 80 

106 90 
10700 
10710 
10720 
10730 
10710 
10750 
10760 
10770 

107 80 
107 90 
10800 
10810 
10820 
10830 
10810 
10850 
10860 
10870 
10880 
10890 
10900 
10910 

ERRORS 



DEFW 


351H 


DEFW 


305H 


DEFH 


0D55H 


DEFW 


0D51H 


DEFW 


0D50H 


DEFH 


0D10H 


DEFW 


ODOOH 


DEFW 


OCOOB 


DEFW 


0C01H 


DEFW 


0C05H 


DEFW 


0C15H 


DEFW 


0C55H 


DEFW 


3141H 


DEFW 


3505H 


DEFW 


3050H 


DEFW 


0C11H 


DEFW 


3101H 


DEFW 


3AAH 


DEFW 


0C11H 


DEFW 






-(- — -) 

BLANK 
ERRORt 



.) 



ifBiKiiiitfffeiiiif MESSAGE BUFFER**** ••»»i*»»t»»*»****» 
■« ARBITRARILY SET AT 2560 BYTES (256 BYTES PER MSG « 
:« PLUS MSG# PLUS 1 TERMINATOR). * 



MBUF 
EN DM 



E8U 
EQU 



$ 
$+2571 



;«««»«B*»»«a**»*»*a»**INPUT BUFFER*********************** 
;* CIRCULAR INPUT BUFFER OF 256 BYTES " 



IBUF EQU 

IBUFE EQU 

TOPS EQU 

END 



EN DM 
IBUF+256 
IBUFE+100 
START 



;T0P OF STACK 



BTAB 


80CD 


CDTAB 


8812 


CDTABS 


002C 


CHARCT 


85E0 


CLEAR 


0001 


CLRCOM 


83FB 


COFF 


8356 


CON 


833D 


CTAB 


8812 


CURCUR 


85E9 


DASH 


8335 


DASHO 


85E7 


DBDEL 


0061 


DBDELP 


0065 


DEC040 


8598 


DEC070 


85B6 


DECBIN 


8590 


DEF005 


80F1 


DEF025 


8126 


DEF030 


812F 


DEF035 


811D 


DEF010 


8152 


DEF050 


817F 


DEFINE 


80EB 


DEL010 


85C7 


DEL020 


85C9 


DELAY 


85C0 


DIS010 


83D3 


DISCHR 


83BE 


DOT 


8327 


DOTO 


85E5 


DSP005 


8370 


DSP010 


837D 


DSPMES 


836D 


EN DM 


92F5 


ENTER 


0002 


FIL010 


858E 


FILLCH 


8583 


FND020 


82D1 


FNDMSG 


82C7 


FNDSR 


82D7 


FTAB 


80BE 


FTABS 


OOOF 


GET065 


853E 


GET070 


8510 


GETCHH 


8515 


IBUF 


92F5 


IBUFE 


93F5 


IBUFL- 


85F0 


IBUFN 


85F2 


INP010 


8111 


INP020 


814C 


INP025 


811E 


INP035 


8156 


INP010 


8158 


INP052 


8178 


INP055 


817E 


INP056 


8197 


INP057 


819A 


INP059 


81B1 


INP060 


81 B7 


INP065 


84B9 


INPUT 


8129 


INPUTS 


810D 


INPUTW 


81F3 


INS010 


8111 


INS030 


8126 


INW010 


8509 


KBTAB 


81 BB 


LASTR 


85EF 


LINE1 


3C40 


LINE11 


3EC0 


LINE12 


3F00 


LINE13 


3F10 


LINE11 


3F80 


LINE15 


3FC0 


LPFTF 


85DF 


LPR010 


8398 


LPR020 


83A1 


LPR090 


83AC 


LPRINT 


8381 


LPS010 


83B0 


LPSTAT 


83AF 


LSTCUR 


85EB 


MBUF 


88EA 


MLDEL 


OOOA 


MOR015 


8037 


MOR020 


8061 


MOR0 21 


8066 


M0R022 


807D 


M0R025 


8083 


MOR027 


8096 


M0R030 


80AB 


MSG1 


85F1 


MSG 10 


87AA 


MSG11 


87C9 


MSG12 


87EB 


MSG2 


86B5 


MSG3 


86BF 


MSG1 


86CB 


MSG5 


86F5 


MSG6 


8720 


MSG7 


873F 


MSG8 


876A 


MSG9 


8795 


NOPRNT 


82B1 


OFF010 


835E 


0N010 


8313 


PRI010 


829C 


PRINT 


828B 


PRINTF 


85DE 


RAN010 


8212 


RAN020 


8226 


RAND 


8512 


RANDOM 


81F0 


RDM010 


851E 


RDM020 


8555 


SCREEN 


3C00 


SCROLL 


83D6 


SEED 


85E1 


SHIFT 


856B 


SND010 


82FE 


SNDCHR 


82E0 


SPACE 


832D 


SPE005 


8197 


SPE015 


81C3 


SPE020 


81DF 


SPEED 


8191 


SPEEDF 


03CO 


START 


8000 


SUB 


8571 


TMP1 


85DC 


TOPS 


9159 


TSLC 


85ED 


TTAB 


8892 


XMIT 


8237 


XMT010 


825E 


XMT020 


8273 











Figure 13-8. MORG Listing 
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The variables are followed by system messages and each 
message is terminated by a zero. 

The CTAB table (Character Table) is a table of 128 ASCII 
characters distributed among all permissible characters. 
This table is used in the Random mode to generate a 
random character. A pseudo-random number of through 
127 is used as an index to pick up the corresponding 
character from the table. 

The CDTAB (CoDe Table) is a table of 44 characters that 
represent all valid characters generated by the system. 
Since these are contained in the first 44 characters of 
CTAB, CDTAB is equated to CTAB. 

TTAB (Timing Table) is a table of 44 entries associated 
with CDTAB. Each entry is two bytes (one word) long and 
represents the coded eight-field representation of the 
Morse code character. CDTAB and TTAB are used to convert 
a valid character to its dot and dash equivalent. 

The next object is MBUF (Memory Buffer), a 2571-byte 
table that holds all defined messages. Since each message 
can consist of 256 characters plus a one-byte header of the 
message number, MBUF is 257*10 bytes long plus one byte. 
The last byte ensures that there'll always be a -1 
terminator for a full buffer. 

IBUF (Input Buffer) is a circular buffer that holds the 
current characters read from the keyboard. You can use it 
to implement the buffered input while characters are 
being generated to the cassette output. TOPS is the "top of 
stack," 101 bytes up from the end of the IBUF area. 

The memory map for MORG is shown in Figure 13-9. 

Program Description 

We'll use a "bottom-up" approach to describe the program 
modules. We'll start at the lowest-level modules and work 
our way up to a description of how the upper two levels 
utilize the other modules to implement the Morse code 
program functions. 
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Figure 13-9. MORG Memory Map 



Delay Subroutine (DELAY) 

The DELAY subroutine delays from 1 to 65536 
milliseconds, depending upon the input count in the HL 
register pair. In addition to the delay, it increments the 
software "elapsed time" variable, TSLC, by the timing 
count. TSLC holds the rough elapsed time in milliseconds 
and is used only for timing the debounce delay. 
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DELAY works by decrementing the delay count in HL by -1 
in DE. Note that the decrement is done by an ADD HL,DE, 
which produces a carry if the contents of HL are positive or 
zero. 

Decimal-to-Binary Conversion Subroutine (DECBIN) 

This subroutine takes a string of ASCII characters repre- 
senting decimal digits and converts it into a binary 
number of through 65535. Entry is made with HL 
pointing to the buffer containing the leftmost character of 
the string and B containing the number of characters in 
the string. 

The result is in HL on exit. If an invalid character is found, 
DECBIN stops conversion and returns with the Z flag reset 
(NZ). An invalid character is defined as one that's not 
30H(0) through 39H(9). 

DECBIN performs the conversion by taking an ASCII char- 
acter, subtracting 30H to change it into binary through 9, 
testing the result for validity, and adding the through 9 
to a partial result in IX. 

The loop at DEC040 is entered once for each character of the 
string. Each time the loop is entered, the partial result is 
multiplied by 10 with a shift-and-add technique. 

Fill Character Subroutine (FILLCH) 

The Fill Character subroutine fills a specified area with a 
given fill character. It operates with a simple loop that 
tests for a decrement of BC down to zero. 

Subtract Seed Subroutine (SUB) 

The Subtract Seed subroutine is a four-byte multiple- 
precision subtract that subtracts the contents of DE.HL, 
(treated as a four-byte integer value) from the "SEED" 
variable, a four-byte value in SEED through SEED + 3. The 
result goes back to SEED. Two subtracts are done, the 
second using a possible carry from the lower-order 
subtract. 
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Shift Subroutine (SHIFT) 

The SHIFT subroutine shifts the contents of DE,HL, treated 
as a four-byte integer, one bit position left in logical 
fashion. SHIFT is used to multiply by two and is called by 
the RAND routine. 

Random Number Subroutine (RAND) 

RAND is a subroutine to generate a pseudo-random 
number. The algorithm for the routine is this: Starting 
with a "seed" value, a new pseudo-random number is 
generated by multiplying by an odd power of 5, modulus 
64K. "Modulus" simply means that the result is divided by 
64K, the quotient is discarded, and the remainder is saved. 
This process is done automatically as the result is held in 
a four-byte integer variable in SEED through SEED + 3; the 
maximum value here is 65535. 

The odd power of five chosen here is 125 (5 to the third 
power). The old "seed" is put into DE,HL from SEED. The 
SHIFT subroutine is then called 7 times to multiply the 
value by 128. The original value in SEED is then 
subtracted three times from DE,HL by calling the SUB 
subroutine three times. The result is the old seed*125. 
This value is put back into variable SEED for the next 
generation. 



Hints and Kinks 13-5 

Random Number Notes 

The algorithm used here is 

R{N+1) = 125*R(N) mod 2 32 

The mod 2 52 operation is automatically per- 
formed by working in 32 bits. 

You can generate about 2 30 or 1 billion numbers 
without repeats in this approach. I haven't 
verified this, having quit after scanning only 
about 1 million cases. 
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A 7-bit mask of the high-order byte of the new random 
number is performed to get a value of through 127. This 
is returned in BC. Of course, B will always be on return, 
but it's convenient to have the number in a register pair 
for further processing. 

Get Character Subroutine (GETCHR) 

The Get Character subroutine gets the next character, if 
any, from the circular input buffer IBUF. During normal 
operation IBUF is being filled with characters as they are 
read in from the keyboard. The characters keep filling up 
IBUF as fast as they're input. Also during normal 
operation, characters are being output from IBUF to the 
Morse Code Send Character (SNDCHR) routine, and for 
display on the screen. 

We use this routine to handle the task of seeing if another 
character is ready for output and display. The routine uses 
two pointers, IBUFL and IBUFN. IBUFL holds the address of 
the next character to be output. IBUFN holds the address of 
the next "slot" in IBUF. If these two pointers are equal, the 
GETCHR subroutine has caught up with the character 
storage. 

If the pointers are not equal, GETCHR uses IBUFL to get the 
next character. It then bumps IBUFL by one to point to a 
possible next character. A limit condition occurs when 
IBUFL points to the last character position of IBUF + l. If 
this is true IBUFL is reset to the start of IBUF. 

On exit, A contains the ASCII character found in IBUF or 
zeroes if there was no character available. The Z flag is 
either set if there was no character or reset if there was a 
character. 

Input Character and Wait (INPUTW) 

The Input Character and Wait subroutine is called to pick 
up a single character for user input. It is not used during 
normal operation, only for response to system queries such 
as code speed and message number. In these cases, no 
buffering need be used. 
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INPUTW calls INPUT to input the next character. INPUT is 
the fast input routine used for all character input. Before 
calling INPUT, INPUTW "dummies up" the "Time Since Last 
Character" variable TSCL to make it look like the debounce 
time has elapsed. It does this each time a new character is 
required. This approach makes it possible to use INPUT for 
both "wait until next character" and "scan fast and 
return" functions. INPUTW does not exit until a character 
has been input to the keyboard. 

Keyboard Input Subroutine (INPUT) 

This subroutine is the high-speed keyboard input 
subroutine that permits buffering of input characters 
during transmission of code characters. INPUT has three 
basic functions: fast scan, conversion, and storage. 

When INPUT is called it loads the A register with 
input/output address 387FH. This address enables all "row" 
addresses of the keyboard. If you are pressing any key, 
there will be a one bit in A after this LD. In effect, this is 
an OR of all rows into eight column bits. If you aren't 
pressing any key, INPUT immediately returns. This 
sequence takes six instructions. 

If there is a one bit in A after the fast scan, INPUT checks 
the elapsed time by testing variable TSLC. If the debounce 
time has not elapsed (DBDEL), INPUT returns since the key 
press may represent the same key input on the last read. 

If the debounce time has elapsed, INPUT goes into the 
conversion processing. It now scans each row by reading in 

I/O address 3801H, 02H, If a one bit is found after any 

read, the conversion routine at INP020 is entered. At this 
point HL contains the row address. The column bit is 
converted to a number from through 7 and added to 8 
times the row value to get an index of through 56. 

The index value is added to the address of the start of 
KBTAB. KBTAB is a table of 56 characters representing the 
keyboard configuration. KBTAB represents the "unshifted 
characters" from the keyboard. The character represented 
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by the keypress is read from KBTAB and put into A. If this 
character is a zero, it is an "ignore" character and a return 
is made. 

The SHIFT key is now read and stored in B. (NOTE: On 
Model III, this is the LEFT SHIFT key.) If the character read 
is either slash (/) or minus (-), the SHIFT key is tested; if 
SHIFT is being pressed, the slash or minus is converted to a 
question mark (?) or equals ( = ) by setting bit 4 of the 
character. 

A test is then made for the CLEAR character. The CLEAR 
key can be pressed to reset operation of the program. If 
CLEAR is being pressed, the program is restarted at MOR015 
after some cleanup of the current cursor position 
(CURCUR). 

If CLEAR is not being pressed, the code at INP057 is entered. 
This code stores the character in IBUF by using IBUFN, the 
variable that points to the next IBUF character "slot." 
After the store, IBUFN is incremented by one. A test is 
then made to see that IBUFN has not gone beyond the end 
of IBUF. If it has (IBUFN = IBUFE), IBUFN is reset to the 
beginning of IBUF. Since a character has just been read, 
the "time since last character" variable TSLC is reset to 
zero, and the subroutine is exited. 

Input String Subroutine (INPUTS) 

The Input String Subroutine is used to input a user 
response to a system question such as that for code speed. 
It calls INPUTW, Input Character and Wait. As each 
character is input, it's displayed on the screen by a CALL to 
DISCHR. INPUTS detects the end of the input string by 
testing for an ENTER and returns with a character count in 
B. The character count will be used in converting the 
(decimal) string to binary in DECBIN. 

Clear Communications Area (CLR.COM) 

The Clear Communications subroutine calls FILLCH to 
clear the last three lines on the screen (the 
communications area). Blanks are filled. 
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Scroll Subroutine (SCROLL) 

SCROLL is used to scroll up the first 12 lines of the screen. 
This is the "text" area used to display text as Morse code 
characters are entered and transmitted. Lines 1 through 
11 are moved up into lines through 10 by an LDIR 
instruction. The last line of the text area, line 11, is then 
filled with blanks by a call to FILLCH. 

Display Character Subroutine (DISCHR) 

The Display Character Subroutine stores a character on 
the screen at the current cursor position. It is used for all 
screen output, both in the communications and text area. 
The current cursor position is always held in variable 
CURCUR as a screen address. After the character is stored, 
CURCUR is incremented by one. If it now points to the last 
position of line 11, a CALL to SCROLL is made. 

Line Printer Subroutine (LPRINT) 

LPRINT is the line printer driver subroutine. If the PRINTF 
variable is non-zero, the "P" command has been given for 
simultaneous line printer output. In this case, the 
character is output to the system line printer. On the first 
output to the line printer (LPFTF = o) and after 32 
characters have been output to the line printer, the 
subroutine automatically outputs a carriage return for a 
new line. This eliminates overprinting in some system line 
printers. 

LPRINT uses an "internal" subroutine LPSTAT to read line 
printer status. 
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Hints and Kinks 13-6 

Line Printer Output 

LPSTAT is a typical line printer driver for 
parallel line printers. The handshaking 
between the computer and line printer is 
probably the simplest of any peripheral. A 
line printer is ' 'ready' ' when it has finished 
printing a character and ready to accept the 
next. The inverse of ready is ' 'busy. ' ' In an 
unbuffered line printer, the busy time 
duration in seconds is 1/N, where N is the 
number of characters per second. 

A status loop checks the busy status (LD 
A,(37E8H)) until the line printer is ready to 
accept the next character, at which time the 
CPU outputs the character (LD (37E8HJ.A) 
causing the line printer to again become busy. 
The busy flag is set automatically by the line 
printer electronics during printing and reset 
after printing. 

Buffered line printers can accept characters 
during printing as long as the buffer does not 
become full . 



Display Message at Location N (DSPMES) 

DSPMES is called for system messages, such as those 
prompting the user to enter code speed. On entry, HL 
points to the start of a message string. This string is 
assumed to be terminated by a zero (null) character. 
DSPMES picks up a character at a time and stores it on the 
screen by using the contents of BC as a pointer. HL and BC 
are incremented after each store. When a null is detected, 
DSPMES returns. Variable CURCUR, Current Cursor, is 
adjusted for each store. 

Send Character Subroutine (SNDCHR) 

This subroutine is the heart of MORG as far as 
transmission of audio code characters. It's called with the 
A register containing the ASCII character to be 
transmitted. 
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SNDCHR first searches for the character in CDTAB, the 
character code table. As SNDCHR can only be called with a 
valid character, the search must be successful. When the 
character is found in CDTAB, its index of through 43 is 
multiplied by 2. The index now can be used to pick up the 
corresponding TTAB entry, which contains the coding of 
dots, dashes, spaces, and terminator. The character is 
picked up from TTAB by adding the index to TTAB and 
loading the character into H and L. 

The code starting at SND010 and ending at the next return 
is the major "output" loop of SNDCHR. The contents of HL 
are shifted two bits right. The two bits shifted out are 
saved in A and tested. They are either 00 (dot), 01 (dash), 
10 (space), or 11 (terminator). If the bits are a terminator, 
the subroutine is exited. 

If the bits represent a dot, the DOT subroutine is called; if a 
dash, DASH is called. 

DOT and DASH call two other subroutines at a lower level, 
CON and COFF. CON produces an audio tone of 500 hertz by 
outputting alternate 01 and 10 to the two least significant 
bits of the cassette latch at address 0FFH. DELAY is called 
to time out the 1 millisecond delay between an on and off 
condition. The output goes on for 1 millisecond, then off for 
one millisecond, producing a 500 hertz square wave. 

COFF is similar to CON, except that it leaves the cassette 
latch off and performs only the delay. 

DOT calls CON to produce the tone for one dot time (DOTO) 
and then calls COFF for one dot time. DASH calls CON to 
produce the tone for one dash-time (DASHO) and then calls 
COFF for one dot time. 

If the two-bit code was a 10 in the main loop of SNDCHR, an 
inter-character space is called for. In this case, only COFF 
is called for two dot times, as one dot time has already 
been output for the last dot or dash. The total elapsed time 
is three dot times. 
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Find Message Subroutine (FNDMSG) 

This subroutine is used to search the Memory Buffer MBUF 
for a given message number. It's possible that the message 
has not been defined. 

A search is made by scanning for a given message number 
through 9. This byte can only exist if a message has been 
stored in MBUF, as other bytes are ASCII characters, minus 
ones, or other digits. 

If the message number is found, FNDMSG is exited with HL 
pointing to the message, otherwise HL points to the next 
available area for the message. A CPIR instruction is used 
for the search in a small subroutine called FNDSR. 

Main Driver 

The subroutines above are used by the main body of code 
to implement the functions of MORG. The main driver of 
MORG starts at START. All "restarts" (as, for example, a 
CLEAR) come back to MOR015. 

The code from START to MOR015 initializes MBUF with 
minus ones, initializes the SEED, clears the screen, and 
draws the line separating the text area from the 
communications area. The restart code at MOR015 
initializes the IBUF pointers and TSLC and outputs the 
initial message. 

MOR020 is the start of the loop to output characters or 
messages. A call is made to INPUT to scan the keyboard 
and then to GETCHR to get a possible character. If no 
character is available, a "minor" count in D is 
incremented. When this count is equal to MLDEL, 
approximately one millisecond has been reached, and 
variable TSLC is bumped by one. This software counting is 
necessary as TSLC is used in the debounce delay in INPUT. 
If it were not done, the keyboard routine could be "locked 
up" waiting for the debounce delay. 

If a character is present, it's either a character to be 
transmitted or a special function that uses the shift key 
and through 9, T (Transmit Message), D (Define 
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Message), S (Define Speed), R (Random), P (Print), or N 
(No Print). If no shift is present, the character is displayed 
(DISCHR), printed (LPRINT), and transmitted (SNDCHR) and 
a return is made to MOR020. 

If a special SHIFT key has been pressed, a table of 
allowable functions, FTAB, is searched for the key. If none 
is found, the keypress is ignored. If a match is found, the 
index from FTAB is used to pick up an address from 
branch table BTAB. The entries in this table match the 
entries for the character. A branch is then made to one of 
six routines that will implement the function required. 
Return will be made back to MOR015 at the completion of 
the function. 

Function Routines 

The Define Message Routine (DEFINE) is entered if SHIFT D 
is pressed. It calls CLRCOM to clear the communication 
area and then prompts the user to input a message 
number. A test is made of the input for a valid number 
and an error message is output if the number is not 
through 9. 

FNDMSG is called to check for a current message with that 
number. If a current message is found, it's deleted by 
moving up the remainder of MBUF on top of the existing 
message. The remainder of MBUF is then filled with minus 
one bytes. 

The loop at DEF040 is then executed. This loop uses INPUTW 
to get a character, store it in MBUF, and display it by 
DISCHR. A check is made for messages exceeding 256 
characters with an appropriate message output if this is 
the case. The main driver loop at MOR015 is reentered 
when an ENTER is input, ending the message. 

The Set Speed Routine (SPEED) is entered if a SHIFT S is 
input. It clears the communication area and displays a 
prompt message for user speed input. INPUTS is used to get 
a character string, which is then converted to binary by 
DECBIN. 
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If the speed value is less than 3 or greater than 60, an 
error message is output, and the sequence is repeated. 
Otherwise, the speed value is used to divide system value 
SPEED (nominally 1200, but adjusted for system overhead) 
to obtain the dot time in milliseconds. This value is stored 
in DOTO. The dot time is multiplied by three to obtain the 
dash time. This value is stored in DASHO. The main driver 
is then reentered at MOR015. 

The Transmit Random Characters Routine is entered 
when a SHIFT R is input. This routine clears the 
communications area. It then calls RAND to get a random 
number of through 127. This value is then used to get a 
character from the 128-byte CTAB. If a blank character is 
picked up, a test is made to see if the last character was 
blank. If it was, a new character is generated to avoid 
sending two blanks in a row. 

The character is then displayed (DISCHR), printed (LPRINT), 
and transmitted (SNDCHR). A test is then made for a 
CLEAR character by calling INPUT even though no input is 
taking place for characters. A CLEAR will restart at 
MOR015, otherwise RAN010 is executed. 

The Transmit Message Routine (XMIT) is entered if a SHIFT 
through 9 is entered. The communications area is 
cleared. At this point, the message number is still in the 
BC register pair. It is used to call FNDMSG to find the 
location of the message in MBUF. If the message number is 
not found, an error message is briefly output and the main 
driver is reentered at MOR015. 

If the message is found, it is transmitted character by 
character until a non-ASCII character is detected (new 
message number header or minus one). DISCHR, LPRINT, 
and SNDCHR are called to display, print, and send each 
character. 

The Print (PRINT) and No Print (NOPRNT) Routines are 
entered by SHIFT P and SHIFT N, respectively. The only 
action in each is to clear the communications area and 
display a short PRINT SET or PRINT RESET message. 
The main driver is then reentered at MOR015. 
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Using This Program 

There are several alternatives in using the program. First 
of all, of course, you don't really have to use it at all except 
for reference. It illustrates many of the concepts we 
discussed earlier in the book. 

If you care to actually run the program, you may key in 
the machine code by using Disk DEBUG or T-BUG. The 
program is assembled at 8000H and, of course, is 
non-relocatable except by reassembly. At first blush, this 
seems like a formidable task, as there are several 
thousand bytes. However, it can be done in slightly over 
an hour for a fast typist. Checkpoint occasionally by 
saving what you've done. Also, mind the locations! There 
is nothing worse than completing a large input of several 
thousand locations and finding out at the end that you've 
been one location off for 1500 bytes! 

A third alternative is to key in the source. This is a 
formidable job, but does allow you to experiment with the 
program once you have captured the program on disk or 
tape. 
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Chapter Fourteen 
Tic-Tac-Toe Learning Program 

We're presenting another larger assembly-language 
project in this chapter — a program that plays tic-tac-toe. 
The difference between this and other programs that play 
the game, however, is that this one learns! It starts off 
playing all possibilities, but quickly learns which paths 
lead to winning games. 

The program was assembled using the Disk Editor/ Assem- 
bler, but can be easily modified to run on EDTASM by the 
simple format changes of adding colons after labels and 
using single arguments on data generation pseudo-ops. 

General Specifications 

I can sum up the general specs for the program in a 
paragraph or so: Write a program that plays tic-tac-toe 
with a human. The program always makes the first move. 
The program must start out by playing any possible 
sequence and must not use any predetermined logic to 
decide where to play, except for the obvious capabilities of 
being able to block a human's winning row, column, or 
diagonal and of trying to complete its own winning row, 
column, or diagonal. 

As the program plays games, it should record the win, loss, 
and draw records of the games. More importantly, it 
should "learn" which paths produced winning games and 
somehow reinforce those paths. It should also learn which 
paths caused it to lose and avoid those sequences. 

The program should, of course, draw a tic-tac-toe grid, put 
in Xs and Os, prompt the human, display the 
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win/loss/draw record, and do all the usual things in 
interacting with the user. 

Operation 

Here again, as with the Morse Code Generator program, 
we can define the operation of the program before actually 
designing it — we can define the external or outward 
operation of the system. Whether or not we can actually 
implement such a program is still a question at this point. 

The program should draw a tic-tac-toe grid on the screen 
as shown in Figure 14-1. The computer's symbol will be an 
X and the human's an O. Initially, and at each new game, 
the title TIC-TAC-TOE will be displayed at the top of the 
screen. 



Figure 14-1. Tic-Tac-Toe Grid 

The computer moves first, placing an X in one of the nine 
positions, and then prompts the user with a YOUR MOVE 
message. The human then responds by entering a digit of 
through 8, depending upon the position in which he 
wants to place an O. After the is placed, the computer 
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plays again and prompts the user. This dialogue continues 
until either the human or the computer wins. 

If the human makes an invalid choice of square (one that 
is already occupied by an X or O), the message 
TRY AGAIN is displayed, and the human must try a new 
move. 

At the end of the game, the program displays either 
YOU WIN!, I WIN, or DRAW and then displays the 
message ONE MORE? If the human wants another game, 
he can press any key from through 8 to start a new 
game. 

At the end of each game, a "history" of the past 128 games 
is displayed on the bottom three lines of the screen as 
shown in Figure 14-2. There are 2 lines of 64 characters on 
the bottom of the screen. As each game is played, a W » L > 
or D is displayed in the next position for win, lose, or draw. 
When the 128 positions are filled up, the history "slides" to 
the left to display the last game and previous 127 games. 



HISTORY LAST 128 GAMES 
DDDLWDDWLWD 



Figure 14-2. Tic-Tac-Toe 
History 
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Messages are displayed in "large format" at the top of the 
screen, except for the history message, which is standard 
alphanumeric size. 

All of the above seems perfectly achievable for an 
assembly-language or BASIC program, with the exception 
of the internal workings of the "learning" capability. We'll 
discuss this major point next. 



General Design 

The general design of this program can be divided into 
several areas of research: 

• Nature of tic-tac-toe 

• Alternatives to learning 

• Algorithms 



Nature of Tic-Tac-Toe 

Just to start from "square one," let's review the rules of 
tic-tac-toe. Tic-tac-toe is played on the grid shown in 
Figure 14-1. There are nine squares in the grid. Two 
opponents play, one using Xs and one using Os (an old 
name for the game is "naughts and crosses"). 

Each player plays in turn, putting his X (or O) into a 
vacant square. The first player to successfully put all Xs 
or Os into a row, column, or diagonal wins the game. If 
neither player can complete a row, column, or diagonal, 
the game is a draw. A sample game is shown in Figure 
14-3. 
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Figure 14-3. Sample Tic-Tac-Toe Game 



Let's start our research by asking, "How many 
different games can be played?" At first, this seems 
like a question for a statistician, but we can draw some 
conclusions about it. 
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Each square can only have an X, O, or space (no play) in 
it. Therefore, we can represent any move of any game by 
listing all possible configurations of Xs, Os, and spaces. 
If we start to do this by hand, we can get confused quite 
easily, as shown in Figure 14-4. 
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There are just too many combinations to keep track of! 
Let's try a different approach. We'll assign an X a one 
value, an O a two value, and a space a zero value. Now 
we can write down any configuration, beginning of 
game, middle of game, or end of game by a series of 0,1, 
and 2. We'll number the squares 0,1,2,3,4,5,6,7, and 8 as 
shown in Figure 14-5. 
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Figure 14-5. Tic-Tac-Toe 
Squares 



Sample configurations are shown in Figure 14-6. The begin- 
ning of a game has all blanks and is therefore represented by 
0-0-0-0-0-0-0-0-0. A typical "middle game" shown in the 
figure has a combination of Xs, Os, and blanks and is 
represented by 1-2-1-0-2-0-0-0-0. A typical end game shown 
in the figure is represented by 2-1-0-2-2-0-1-1-1. 
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BEGINNING OF GAME 

SQUARE 
012345678 

0-0-0-0-0-0-0-0-0 



O 



% 



TYPICAL MIDDLE GAME 

SQUARE 
012345678 

1-2-1-0-2-0-0-0-0 






K 












X 


X 


X 



TYPICAL END GAME 

SQUARE 
012345678 
2 -1-0-2-2-0-1-1-1 



Figure 14-6. Tic-Tac-Toe 
Configurations 



Figuring Permutations 

How many different combinations, or more precisely, 
permutations are there of Xs, Os, and spaces? We can 
find out by listing all permutations of the numbers. We'll 
start with 000000000, and end with 222222222. We've 
eliminated the dashes for compactness. 

Wait, a minute, this looks suspiciously like a range of 
numbers, not binary, since there are three symbols, but 
base three. This is no more mysterious than binary! 
There are three symbols, 0, 1, and 2, and we count much 
the same way — 0,1,2,10,11,12,20,21,22, 
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Hints and Kinks 14-1 

Base 3 Numbers 

Base 3 numbers ( ternary) use the same 
positional notation as binary, decimal, and 
hexadecimal. The rightmost digit is 3°, next 
is 3 1 , and so forth. 

2iZ 
I I— 



-2^30= Z 

- i x 3 1 = 3 
-2 x 3*=J8_ 
23 

The same conversion techniques used in binary 

or hexadecimal can be used to convert between 

decimal and base three — double dabble: 
i 



202 



i 



2*3-6 +j0= G 



6*3 = 18+2 = 20 
20*3=60+1 =£1 



and 



'divide by 3, save remainders' ' : 
R2 

3[~2 m 

3f6 R2 
3^10 Rl 
3 [61.. 



2021 



Just as a nine-digit binary number can hold 2 to the ninth 
permutations, a nine-digit base three number can hold 3 to 
the ninth permutations, or (let me use my pocket 
calculator here) 19,683 permutations. 

One of those permutations will represent any 
arrangement of Xs, Os, and spaces we care to define. Many 
of the permutations are not possible in a game, such as 
111111111, 222222222, 222222000, and many others! 

As a matter of fact, we can write a fairly simple 
assembly-language program to figure out the number of 
permutations we'll have to work with. 19,683 
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permutations are really too many to fit into memory with 
everything else. We'd like to see if we can reduce that 
number down to something manageable! 

Reducing the Number of Permutations 

We'll start by making some assumptions about the game 
to simplify things. First of all, the computer will always 
play first with an X. Secondly, we'll look for those 
permutations in which the computer is to play next, not in 
which the human is to play. We'll never have to deal with 
the latter case. This means that the number of Xs and Os 
have to be equal. 

A flowchart for such a program is shown in Figure 14-7. It 
cycles a variable from 000000000 through 222222222 in 
base three. For each number, it tests the number of Xs 
(ones) and Os (twos). If they are equal, it adds 1 to a count. 
At the end, the count has the number of possible 
permutations of "computer to play next" (this includes 
000000000 where the computer has not yet played, but 
#Xs = #Os = 0). 
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000 008 000 
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VARIABLE = 
VARIABLE 



ADD ONE IN 
BASE 3 




ONE MORE 
THAN 222 222 222 



YES - COUNT HAS # OF 
PERMUTATIONS 



Figure 14-7. Flowchart Try # 1 

When we run such a program, we find that there are about 
3200 such permutations, a large reduction from all 
possible permutations of 19,683. 

Still, we would like to reduce the permutations further. 
Well, we can delete all permutations where the game has 
already been won! We'd never continue from such a point 
in an actual game. This would be the case in which there 
are three Xs or Os in a row, column, or diagonal. The 
flowchart for such a program is shown in Figure 14-8. 



( START J 



9-»-COUNT 

999 999 999 

— » VARIABLE 




• GAME OVER 
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VARIABLE = 
VARIABLE 




ADD ONE IN 
BASE 3 



— ONE MORE THAN 
222 222 222 



r 

I DONE 



J 



Figure 14-8. Flowchart Try # 2 



When we implement the program, we find that there are 
now about 2460 valid permutations, a further reduction. 

Another reduction we can make is to eliminate "9th move" 
permutations. In this case, 8 squares have been filled and 
the computer has only one choice. When this is added to 
the analysis program, we have cut down the allowable per- 
mutations by another 100 or so. 

We can reduce further by eliminating permutations where 
there are two Xs in a row, column, or diagonal. This 
means the computer will win on the next move and knows 
enough to finish the game. This reduces the number of 
permutations we have to deal with still further. 

Are there any other reductions possible? Yes, a major one. 
We know that there are many configurations of tic-tac-toe 
moves that are identical except for rotation. Figure 14-9 
shows some of these. Also, there are identical games when 
"mirror images" are considered. We can cut down on the 
permutations we have to deal with drastically by consid- 
ering rotations and mirror images. 
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Figure 14-9. Rotation Identities 

There are eight rotations and mirror images to consider, 
and they are shown in Figure 14-10. 



X X 



X X 











X 
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X 



X 



X 



0° ROTATION 
(NO ROTATION) 



90° ROTATION 



180° ROTATION 
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xo X 





X X 







X X 







X X 
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X 
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X 











X X 
X 







X 



270° ROTATION 



0° ROTATION 
MIRROR IMAGE 



90° ROTATION 
MIRROR IMAGE 



180° ROTATION 
MIRROR IMAGE 



270° ROTATION 
MIRROR IMAGE 



Figure 14-10. Rotations 
and Mirror Images 



Our analysis program now eliminates: 

1. All permutations in which the number of Xs and Os 
are not equal. 

2. All permutations for the last move. 

3. All permutations in which the game has already 
been completed. 

4. All permutations in which the computer will win on 
the next move. 

5. All permutations which are rotations or mirror 
images of other permutations already recorded. 

The flowchart for figuring out the number of permutations 
we have to deal with is shown in Figure 14-11. 
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f start") 

i 

0— >COUNT 
000 000 000 
— > VARIABLE 



FIND ALL 

8 ROTATIONS, 

MIRROR 

IMAGES 



YES - COMPUTER 
MOVE 



NO - NOT LAST 
MOVE 




YES- 




COUNT = 
COUNT ■*•! 



| NO- GAME NOT 
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IN ROW, COL, 
DIA& 
? 



I NO- COMPUTER WILL 
■if NOT WIN ON 



SKIP THIS 
ROTATION 



VARIABLE =• 
VARIABLE t 
I 




MOVE 



Figure 14-11. Final Flowchart 

What do we really have after totaling the number of 
permutations in this fashion? We have a complete record 
of all configurations that we would encounter in any 
tic-tac-toe game in which the computer plays first and 
knows enough to complete a row, column, or diagonal; to 
recognize that the game has been lost; and to recognize 
that it will win on the next move. More importantly, the 
number of permutations we have to deal with have been 
reduced from 19,683 to 120! Now we can fit the 
permutations in memory and possibly implement the 
program! 
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Alternatives To Learning 

Given a reasonable number of permutations to work with, 
how do we implement artificial intelligence in the 
program? How do we make it learn? 

One approach would be to implement some sort of giant 
binary tree structure in the program as shown in Figure 
14-12. We'd start off with the "empty" configuration and 
construct all possible courses a tic-tac-toe game could take. 
Then, if the computer lost, we would delete the last move 
so that the computer could never make that play again. 
When all possible lower branches were deleted, we'd delete 
the upper "limb." Given enough games, we'd have a 
computer that "learned" by never making the same 
mistake twice. 




ETC. 



Figure 14-12. Tic-Tac-Toe 
Binary Tree 
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Hints and Kinks 14-2 

Learning By Losing 

If we implemented the ' 'learning by losing' ' 
algorithm, we'd have a very mechanical 
learning machine, and we'd have to play 
hundreds of games to make much progress. 

What we really want is not so much an 
infallible ''idiot savant 1 ' as something 
that will emulate human learning - learning 
by trial and error with reinforcement of 
successful actions and rejection of 
unsuccessful approaches. 



Another way to create a learning process was described in 
the pages of Scientific American some years ago, and 
attributed to work done by Michie at the University of 
Edinburgh. Suppose that we emulate the tree structure 
described above by a series of boxes. Each box is marked 
with the permutation that we've allowed by our analysis 
program. 

Inside each box, we put different colored balls, each color 
representing one of the paths that could be taken. There 
could be nine colors for a "first move" configuration, seven 
for a "third move," five for a "fifth move," and so forth. 

We'll put four balls of each color into first move boxes, 
three of each color into third move boxes, two of each color 
into fifth move boxes, and one of each color into seventh 
move boxes. By the ninth move the game will be over, and 
we have no ninth move boxes. This situation is shown in 
Figure 14-13. 
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"FIFTH MOVE 
CONFIGURATION' 




TWO BALLS OF 
EACH COLOR FOR 
FIFTH MOVE. ONE 
BALL SELECTED 
WHILE BLINDFOLDED. 



IF THIS BALL SELECTED, 
COMPUTER: 

PUTS X IN SQUARE 3 
PUTS X IN SQUARE 5 

PUTS X IN SQUARE 6 

gV) PUTS X IN SQUARE 7 

5)) PUTS X IN SQUARE 8 



Figure 14-13. Boxes and Balls 

Now we'll play a game. For each move, we'll shake the box 
and withdraw one ball. We'll note the color and put it back 
in the box. Its color will determine in which square the 
"computer" will play. The human now makes a move. 
After the human's move, we go through the process again, 
choosing one ball at random from the next box 
representing the current configuration. 

Eventually the "computer" wins, loses, or draws. If the 
computer wins, we'll go back and add three balls for each 
color chosen to each box. For example, if the first move box 
was a red, signifying square 2, we'll add three red balls. 
We'll also add three balls of the appropriate color to the 
third move, fifth move, etc., boxes. 

If the "computer" loses, we'll take away one ball of the 
proper color from each of the boxes involved. If the 
"computer" draws, we'll add only one ball of the 
appropriate color. 
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If a particular color (which is really a number of a square) 
consistently wins, we'll start accumulating a higher and 
higher proportion of balls of the color (square) that 
produces winning games. Similarly, if a color consistently 
loses, we'll have fewer and fewer balls of that color. 

Since one ball is chosen at random for each move, we'll 
have a better chance to withdraw winning colors (squares) 
as more games are played. Winning games "reward" the 
square choice, losing games "punish" the square choice 
and draws "reward" the choice slightly. This emulates the 
reward and punishment of human learning for a 
mechanical process and is much more interesting and 
faster than just deleting losing paths. This is the method 
we've chosen to adopt in our implementation of tic-tac-toe 
on the TRS-80 in this program. 

Algorithms 

The algorithms we'll be using for the tic-tac-toe program 
are described in the following section. These algorithms 
emulate the tic-tac-toe learning procedure described above 
— the "reward" and "punishment" method. They are 
divided into two parts: 

1. Generation of a table of permutations representing 
legitimate tic-tac-toe games, and 

2. Algorithms for playing the game itself. 

Generation of a Permutation Table 

First of all we must generate a table of all the possible 
permutations the computer will encounter in playing the 
game of tic-tac-toe. As we described above, these represent 
configurations where the computer is to play: the so-called 
"first move," "third move," "fifth move," and "seventh 
move" conditions. 

In generating the permutations, we'll discard those where 
the game has already been won or where there are two Xs 
(computer) in a row, column, or diagonal. We'll also look 
for the "rotations" and "mirror images" and pick only one 
out of eight possible, discarding the rest. At the end of the 
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table generation we'll have a table of hundreds of entries 
that represent any configuration that the computer will 
encounter when it is playing the game. 

The algorithm for table generation is as follows: 

1. Start with a value of the base three number 000 000 
000. Increment this value by one each time through 
the steps up to a maximum of 222 222 222. This 
value is known as the "current value." 

2. Start with the address of a table in memory known 
as the "permutation table" or "PTABLE". For each 
valid permutation, we'll enter the current value and 
some other data. We'll build up this table so at the 
end of table generation, we'll have a table in 
memory that holds all configurations. 

3. Take the current value. Test for the end of 1 000 
000 000 (one more than 222 222 222). If not equal, 
continue; otherwise the table is done. 

4. Count number of Xs and Os in current value. If they 
are not equal, this is not first, third, fifth, seventh, 
or last move (computer's turn); if not equal, go on to 
the next current value. 

5. Test for number of Xs = number of Os = 4. If this 
is true, this is the last move. The computer knows 
what to do here, so go on to the next current value. 

6. Test for all Xs or Os in a row, column, or diagonal. 
(All ones or twos). If there are all ones or twos, 
discard this permutation as the game has already 
been won. Go on to the next current value. 

7. Test for two Xs (ones) in a row, column, or diagonal. 
If this is true, the computer will know enough to 
finish the game as it is the computer's move; go on 
to the next current value. 

8. Rotate (and find the mirror image) of the current 
value seven different ways. Take the lowest base 
three value and compare it to the current value. If 
they are equal, save the current value in the 
PTABLE, otherwise go on to the next current value. 

9. At this point we have a "valid" current value, one 
that will be saved in the PTABLE. A sample current 
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value that reached this point is shown in Figure 
14-14. Follow the next steps to "process" that value. 



o 







x 



X 



X 



1. VALUED 000 902121 

2. PTABLE ADDRESS = 9003H 

3. VALUE¥1 090 000 080 

4. #Xs = #Os = 2-OK 

5. #Xs = #Os¥4-OK 

6. ALL Xs OR Os IN ROW, COL, OR DIAG — NO 

7. TWO Xs IN ROW. COL, OR DIAG - NO 

8. ROTATE AND MIRROR IMAGE VALUES 
O 3 000 002 1 21 
90° 1 00 200 1 20 
180° 1 21 200 000 
270° 021 002 001 

0° MIRROR 000 200 1 21 

90° MIRROR 001 002 021 

180* MIRROR 121 002 000 

270° MIRROR 120 209 100 

9. LOWEST VALUE = CURRENT VALUE 



o 



X o X 



0° MIRROR 



X 



X 



O 90° MIRROR 



X 

x_ 

O 180° MIRROR 



X 



o 



X 



270° MIRROR 



Figure 14-14. PTABLE Initial 
Processing 

10. Enter the current value in the next position of the 
PTABLE. 

11. Count the number of spaces in the current value 
(number of zeroes). Put this number in the next 
position of the PTABLE. This will range from 9 
spaces for a first move to 3 for a seventh move. 
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12. Allocate a number of bytes equal to the number of 
spaces from 11. 

13. Into each of the bytes, put a value of 4,3,2, or 1, for 
9,7,5, or 3 spaces, respectively. In other words, if the 
number of spaces is 5, put a value of 2 into the two 
bytes allocated for the spaces. The entry for this 
permutation is now completed. The sample is shown 
in Figure 14-15. 



9003H 
4 
5 
6 
7 
8 
9 
A 



PTABLE 



46H (000 002121) .. ^j. 



IN BASE 3 



- 10. ENTER 000 302 121 IN FIRST TWO BYTES OF NEXT PTABLE ENTRY. THIS IS 0046H IN HEXADECIMAL 
-11. tt OF SPACES = 5. PUT # IN NEXT PTABLE BYTE 

- 12. ALLOCATE 5 BYTES FOR # OF SPACES 

-13. PUT INITIAL VALUE OF 2 INTO ALL SPACE CELLS 



Figure 14-15. PTABLE Final 
Processing 

What we've constructed in the PTABLE above is a computer 
analogy to the "boxes" we discussed earlier. Each box 
(entry of PTABLE) has a configuration associated with it 
represented by the current value. Each box (entry) has 9 to 
3 "cells" (bytes), each representing a space or move the 
computer can make, reading left to right, top to bottom, 
the same way you would scan a page. 

Into each space cell, we've put a value which is the same 
as putting in a certain number of colored balls. 
Considering all space cells together, we have a number of 
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balls, each representing a certain move. We'll add to or 
subtract from this count by changing the number in the 
space cells as we total up games. We'll withdraw one ball 
by choosing a random space cell of the 9 to 3 space cells 
available. We'll discuss this in more detail in the next 
section. 

Algorithms for Playing the Game 

Having established the "PTABLE", which represents any 
possible configuration that the computer will have to deal 
with, we'll now look at how the game is played by using 
the table to emulate the "boxes and balls" approach. 

The algorithm goes like this: 

1. Start with a blank array drawn on the screen with 
the usual grid. 

2. Take the current array configuration and "analyze" 
it — count the number of Xs(computer), Os(human), 
and spaces. If entering this step from step one, the 
array will be all blanks. 

3. See if the computer can complete a row, column, or 
diagonal of Xs. If so, perform the completion and 
display; the computer wins. Record the win and go to 
step 9. If not, continue. 

4. See if this is the last move. If it is, the computer 
makes the only move available and outputs it to the 
screen. Then the computer analyzes the new 
configuration and sees whether it wins, loses, or 
draws and goes to step 9. 

5. At this point, the PTABLE has not been referenced, 
but the computer has looked for obvious moves. Now 
the PTABLE will be referenced. The computer now 
performs all seven rotations to find which of the 
eight configurations should be found in the PTABLE. 
The PTABLE is then searched to find the proper one. 
This search must be successful, as the PTABLE holds 
all permutations! 

6. Now the computer looks for two Os (human) in a row, 
column, or diagonal. If this condition is found, the 
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computer "blocks" by putting an X in the proper 
space, displays the screen, and goes to step 8; 
otherwise, it continues. 

7. At this point, no "block" was possible. The computer 
now "draws a ball" by randomly choosing one of the 
space cells from the PTABLE entry. It records the 
space cell number, puts an X in the array, displays 
the new array on the screen, and continues. 

8. Now the computer inputs the human choice. It 
checks for the proper choice, displays the new array, 
and analyzes the new configuration. If the human 
wins, it records the win and goes to step 9. If there is 
no win (there cannot be a draw), the computer goes 
back to step 2. 

9. This is the "end of game" step. The computer has a 
record of all configurations and which space cells 
were chosen for the computer's move. If the game 
was a win, it adds 3 "balls" to each of the space cells 
by increasing the count by three. This may require 
three adds for a five move game, four adds for a 
seven move game, or five adds for a nine move game. 
If the game was a loss, one "ball" is subtracted from 
the each of the space cells. If the game was a draw, 
one "ball" is added to each of the space cells. The 
computer now records the win/lose/draw for the 
record, and goes back to step 1 for a new game. 

There is one slight addition to the above algorithm. If in 
step 7, all space cells were found to contain zeroes, the 
computer concedes and zeroes the previous space cell 
that resulted in the current permutation. In this case, the 
current configuration is considered so hopeless that it is 
discarded. This condition will rarely, if ever, happen. 
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Implementation 

Modules 

Tic-tac-toe is implemented as a series of five levels of 
modules as shown in Figure 14-16. The top levels of 
modules are the main drivers of the program, while the 
bottom level has the most rudimentary subroutines of the 
program. 



"HIGHEST 
LEVEL" 


MAIN1 


MAIN 2 


MAIN 3 


MAIN 4 


LEVEL 1 


MEMORY 


HISTUP 


ROTATE 


NUMBER 


ANALAR 


ARRXLA 


DRAWL 


SCRNDS 


MSGOUT 


LARGEC 


DSPMES 


INPUT 


RAND 


BINBAS 


BASBIN 


DIVIDE 


DELAY 


FILLCH 


"LOWE 


ST LEVEL" 


SYSTEM 


LEVELS 





EQUATE 



Figure 14-16. Tic-Tac-Toe 
Modules 



As in the previous MORG program, each module is 
dedicated to a function applicable to the tic-tac-toe 
program or to a general application usable in programs 
such as division. 
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Figure 14-17 shows the module interconnections. Each 
module generally calls a lower-level module by a CALL, 
with a set of parameters in the CPU registers. 
Communication is also done by the tables and variables in 
the SYSTEM module, which are commonly accessed by 
many different modules. 



Hints and Kinks 14-3 

Notes on Figure 14-17 

Here, as in Figure 13-7, it's interesting to 
look at the interconnections to see how the 
modules relate to each other. Most of the 
action takes place in the level one modules, 
which call many of the other modules from all 
levels. One reason for this is that this 
program has heavy processing taking place in 
' 'main-line' ' code of MAIN1 through MAIN4. 

The flow of the program is sequential in these 
modules and couldn't easily be broken down 
functionally into lower-level subroutines. 
There's very little downward communication 
from level two to other modules. 



To find the modules called by any specific module, follow 
the horizontal line from the module to the extreme left. 
When the line turns downward, read the lower-level 
module called by referencing the connection dots. The 
arrangement of the modules is duplicated in the program 
listing. Higher-level modules appear first, followed by 
lower-level modules. 

Tables, Buffers, and Variables 

Refer to the tic-tac-toe listings, Figure 14-18. There is one 
listing for each module. These were assembled on the Disk 
Editor/Assembler, but could have just as easily been done 
on EDTASM as one large program, providing memory 
requirements were not a factor in your system. 

359 



CC _J 
O <C U] 

w a: 

DOS 



<C (O OS S 
H < l-J M 



cc * CJ at 



Hide ^ « 



u 



J H O M 



•a; CO 



J I-. M Sh 

aonK 
« o *= o= 

< w ra< 

- £ - - 

t- H J cc as 
U3 -a: 3i O £- 

z (-* «e e to 

M O 0= W M 

j cc q £ x 



Q X 



•M 


as 


to a. ra ~ 


K 1 


as 




UaHh 




ns 




ZHldQ 


H < 






a. to > 2: 


W < 






on M O M 




W 


<= 


a x £ as 


u. 



x x a: x 

o o o o 

o o o o 

u u o u 



r-Q- U W U Q E- 1 f 

M £-< CC X -i 0= W - 
< PS U 3 M o os ; 



a. CO r- m 

f- X «- * 
O - O • 

-O £ ■» 

cu to ••* s 

co X o * : 

O - t- o i 

3 CVJ O * ' 

- o on * i 
O co X » ■ 

) O E -* 
: z - j * i 

] »r- £-. « - 

■ X O EO ■» 

, o to < • 



as « 
a- o 

o * 



w w w f 
<WHC 
J W X * 

brf eu E : 

CJ C0 U4 to CO u. 

«: O O W M >* O S 

f- M ZflK 

WIt-H O E-« . 

a. as "3 -J t* os c 

E~. <£ -a: J W<> 

W os &■* m m »~f H ► 

CO O W t- tn X W ( 



■a: KWIOZW 

-co » --3 - -°- 

W<QOft.IiaQ 



E-* 




CO D3 CQ 






o to to 






a, j X 


M 




fl 






cc cc - - 


OS OS 




&j «* w w 


W W 




>■ x ^: ^: 


E-« E« 




>^ (J W W 




U) 


c-4 J -J 


< OS 


^: 


H fa. 


OS O 


o 


05 O C*. En 


*£ tn 


Q 


o o o 






x % 


U E- 




H H 






Q Q OS 05 


E~< C*l 




<c <: < <n 


Ul t* 


O 


O O E- S- 


o — 


CJ 


JJWW 



E-i co — * — >~* — 

a o •- oj m a- 

m — o + + + + 

OS X i- X X X X 

CJMXOSHMMM 

..*_»&* <c^- — — — 



S O C-3 t-> 03 J X 



HZO 






jQOO-OSQQOQ 



loooooooooooaoo 
rig- u\io c— co o^o T-ryma- 

55S55ooooooo5oooo-ooooooooooooooooooooooooooooo 
ooooooooooo oooooooooooooooooooooooooo< 



J o o o o o o o 



o oooooo OO oc 

O O =T o o o o 

OOOCHOOOO t-UJ£i,\oIi1u 

OCOOOOOOO CVJ t- Ctj *- J3- J 



oooooo'-'^- r-^-r-cvjcvjcyrvjry 
OOOOOOOO oooooooo 
oooooooo oooooooo 



360 



< CO O O 



o X co r-3 t-j oH O 









<£ t~t 




CO 




-_-,-, 




E-« 




— v O fe, 




w 








:=- 




x e: co 


~J o o 


o 




cj W M OS 


3 ui m o 


x 


en 




«-_-.-.£-. 






_J O M — 


OS O X EC 


w 


i 1 


w X -~* - 


QBH<H 


*= a 


CQ 


El. -_-■ __" «— 



to a 
o « 

M a 



X a 



o w 




M 




a. a 




J 












Sh _3 
















O X 




o 




E-> OS 




E-f 




to o 




CO 








M CU 




IE CO 




3= O 


t- 


M 






«s 


w X 


V. 


w to 


■a: 




!-. 


M CO 


t-l 


M Eh 


S5 


M Ed 


C) 


_J O 


<-: 


-J X 





1 OS cc 
: H H es 

: x x to 

: O o 
lOOH 



2HD3UID 



f-. E- - 

f- CO C 



i £-> as H O J 



<- OS 
3r O 



-_> HI 

e-i to 
» o 
O a, 



w x w -s 

O M CO O 
X 3: __: o 



as t_) o H 

Q S* CG *H 

a ■< w z 

< to M M 



t\j Ed 
CO 33 O cc . 

njuwu: 
■-JEWC 



* to cj 
: x co 



- _~ s » - 

■; cu «£ a, -g 

3 =: X X X 

J O E-i O 3 



s *— a -- q - 



O ■■ - 

O 55 
CO O _ 

x m : 



J4 JZ 



: cj a a k q a . 



-j x 



a o o 
--.he 

W H 
E-t « < 

I M X Ed 

UU.3H 

-t E-* CO CO — 3 

: i W3Q. 
s cj > o x 

-I M O -= O 

i. -~> X S-. CJ 



OOOOOOOOOOOOOOOOOOOOOQOOOOOO(___ 

-ryms'ifivnh-mar,^ n,m -T tn«>*-co<no.-{\im.=rin<3 t^a.cr.a--c_ro._r i^ot-coS 



r>u3smoiot-cy(njrin s0 twcocno'- ojt 
oooooooooooaooo o o < 



JOOOOOOOOOOOOOOOOO 



ooooooooooooooooooooooooooooooooooSooSooSoSSS 



o in 
o o 

o o en m 
O O O w 


0000 
0008 
0000 
0000 


o CJ 
o oj 

O r- 

o o 


Q-Qto 
O O O t- 


■a: t- o cj m 


■< t— t\J 
(OKI tj 



W »-^ii] co cr> o fcu c\i mco o* 

oooo ooooo ooo 
ooooo ooo 



oooo 



* • o oooo o»o* 

ODuO oooooeooooo 

O Et, COOO OCQOO O 

ot. m oooo--ocqoo--o 

ot. in ojoooc\ioooot\jo 



OQofnt~-co«-:ootnc-- < <:c-i omt- 

oooooooooooooooo 
oooooooooooooooo 



o o 

o o 

o o 

o o 



361 



w H<t<!Ht 

s-. q o « oa to 

2«>-Z HK £Ct- 

Ejr\jccCjj£jjcc;<£OMC 
a ma eO £- a, 2 

C_) CM Si. CS CC M h 

S> CM [ij CO CO H E > > 

<(V JHOMOO<' 



KHfcl 3 



1 O CU re 



-a d- o w a o i 



cc >-«. «. <k 



w 



a iu ■ 
i 

o til I 

•. Sri ! 

EG OC «* 

« E i 



CO O bl 




re J 




a; 


&-, £C O &4 


J to <6 


O 


O «S u o 








to >- := 




co ua - to 










E 


W 5h 3 Cd 


e- m 


Z3 


K»jOffi 


«S 3 




O. <C K Q 




o 


q sb a 


M O Z •"I 


u 


<si <C CO <E 









J-W-U3 [d H* «C £- S 

co to a. re a : 

l« O U. X u, OK 

JOE c 

DjorsO:ziOt0; 
3<:aHomaF-' 



CO E-* 3: CK 



o «- 



en o 5- o a; < £-< 1 

*- pa cc m < ra s- co : 

-<c - •.=» o x : 

jo j -j x m re t 

XatlNSHfflwt,! 



■I O Jm £■« 

t- <C J 

3 CC CK <C - 



CM CC C 

o o c 



: a j o J J - 



l QDB'KOC 



CO 


-r 


r-3 


. 1 


«S 


6-* 




M 


a: ca n: 


a. x 






<: 






to 






o <= 








m 




;^= 






3= 






re 


!_, 


O 














o 


£-1 


fc. 


z 






, ** 






la* 




_. E-< 


« 




J 




o. 




i_ 




= CO 


cc 


a 


<C Q Q 


CO W 






CO 




O M 


UJ 


J 


O J J 


X £-< 






UJ 


2". 


3 £- 














(-■ 


o 




ri 






Cu o« 








O 


r;<-> 








O E 






■■* 




W CO 


E 












o 


t-f 


w J 


" 












53 


« 


m <c 


o 








cc 

















: m t-j •— t-i c 



j O -s c_> 



O z O t 
a. a, cw 2: "3 Q . 
-3 o *-a M Q 



ooooooooooooooooooooooooooooooooooooooooooooo 
or-cM rniTinxDf-iacvOr-ryma'ifivDC-cooiO'- cm m^ i/i^t-wo'O'-Ntn^ irno t~co w o >- cy mir 
cf.(r.chcnaia>o-cn^O'OOOOoooooo'-'-r.^'-r-r-rr.^(\| N [\iN W N(\jNNwmminmm 

oooooooooot-'-'-'-''— <-'-'—'— •~* -, -- r ~ T ~'~'~''~ r ~ T ~'~ r " T ~ ,— *~ r ~ T ~ , ~*~' — *- tt *r ^r *r it 

ooooooooooooooooooooooooooooooooooooooooooooo 



o a e 

o o o 

o o 

«- o o 

CM O O 

I CM 



* m * 

o o o 

o o o 

o o o 

o o o 

r~ a ■=: i 



o « « 


• 


o o o 




o o 


<j; *s; -S 


«~ O CO o 


0-1 O O O CM O 


CM O O O 


O O O O O O 



CO CD CO CO CO CO CO CT> C^ 

ooooooooo 
ooooooooo 



CT* O tt* CMrOiXJC—CT!* 3 ! 

ct^ o^ o =e «n -< «a; «< «< 
ooooooooo 

OOOOOOOOO 



BlfflBtOPCQfflUOUUOU 
OOOOOOOOOOOOO 
OOOOOOOOOOOOO 



362 











>-f 


zr 




O 




Q E-. 






















a 


US 
U3 




=c 




























a. 




U] 




O t- 


CXI 


























J L>3 


UJ 


E 3 














_J 








eo 






m t-< 


H 


to O 














<c 








M 


-J 




<q >h 


X 
















\s-. 








;e 










,~. m 














M 




IK 




o 


<2 








J 


us 












O 




< 




J 


■* 




e- to 


E/1 


CO 


UJ 
















tJ 






o 




X ~i 


r 




u. 


















OS 


t- 


J 




u 




-O 














O 




OS 




o 


-1 




a w 


UJ 


>-< w 


















<C 




H 






OS 


US 






a. 












;> 


W 








H 


f-> o 


o 


o 


E-. 


r: 


O 




E- £-. 






•=: 


~! 


O 


Lu 


u. 




b3 E- 


H 


OS 


UJ 




H 




uj o 




o 


t/J 










O 


o w 


UJ 


Q OS 


{•} 


£Q CO 


us 


o °- 














5G 








J UJ 
EC CO 

o a 








UJ 
K 







CO E- 

3! U X 

Hub] 

3: fl- 
ow OS tO 

S O UJ 

m ==. u. c_j 

+ HUH I *5 

ck as q s a; w a. 

E- *s o &■< :=» w 

=s e- o o =s <s 

a- to f- cj a. to ^ 



(M > H h H < l/i 

«=CO'-fOOCOOQ 



jaao 



2 5K C 

=> o * 

CQ U £ 



: x x to -x x - 
4tHMQfnMi-f«3:«= 



OODWi-. j 

WH W<D X :> 

s: cs e —j o m *■ 



at<>-rN: 



) a. co 

: uj o =3 c 



J a. U -J =s ~j -3 . 



: o a a -n, c 



ooooooooc 



joooooooooooooooooooooo 
> oi o ^ cy rn^ in >^> t~ ca en o ■- ojmsrmvot— co o> o 

IOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 



o o o o c 
O o — o rn o t 

O O O O O O f 



Ntna-iA^ o\ <t u U« 

a a a a n qqqq 

ooooo oooo 

O O O O O O'O o o 



OJ M3 CO UU.O(nint-0\BCJUOt\l(ni/HOCMJWr-rrH£i<QliCMiriiflOi 

UJ UJ UJ WWO*U.Uit.ti4U.Ct 1 fc.OOOOOOOO>--T--i— .— r-t— C\JC\iC\JOJ 

OOO OOOOOOOOOOi-'— ^ i—v-r-f-T— r-r-^-^-r-i—r-r-T-^ 

ooa oooooooooooooaoooooooooooooo 



363 



- - » 



x zs ax < j 

B O « c ra in 

ffi O < K =C O 

< en ca <£ E-i co 
- S - - n- E 

r-HjcsccKcocs^ 
W<C3:Of-'E~' , -Hf-'0 
a £~* =~ X W Q x ^ co 
"•HOtKCdw^'HE-'E 

JCCQEECHXO - 

.. - - .. -csitcrn 
>» « W il a - - -a 

<<P.W>ZWO - 
UHl/Jt-'Ol-lCKEOJ 

co < o x 2: a; tn -o 

„-*-„_ -O CO 

a,sKxwcacQoor:' 

(MJHHUaHhEH -I 

aswmJKCsJLd - <- ; 
t-iMa;2:>-iKM<>xot 



< K CO 




[il 


CO <C CO 


Til 


:-; 


CO ^* w 


f/1 


rii 


UWE 




■j 



1 W S 

i :> O 
o u 



i a. o <= a < < 
; t- o J « <= cc c 

iDOBOWEt 

j o tn Q fct- c-j <c : 



N O H M 

>4 X f- J E~4 CO 

<_3 CC < W Id O 

a: <s «; >• o f- o 
< < uico 



a. w 
O ip 

o * 



: co a u- w o « 



i W W JH w 

i H« w W o =s w : 

lOWOCCHO C6X» 

i z» B)uao>- mow 

i wEC0Oro-a:a\ •=: -5 * 

im«J?mco-JUO una 

i >• w « 

I K* * 

i E- « « 



a* « 



a ed a htHi-Hht-^f-HHt 
a os M:zxx:xxxxxx:> 



E J 

o «=: «- ca 

3 CJ 2= ;m H 

m o <c J 

> «o«k < -" 

o a < e «j; z: - 

2: — . o w «c j <c 3 

- J H Q -*£ -CO - 

_j ec > x a ^ - 
*> a: — cQ'K'-t'^scQ* 2 
o o 

Ii4 - 



O t_) W ED -J 

o'QstdjQ-^QQcaa.a; 

U JHWO JU J J JOT 



000000 000000000000000000000000000000000000000 

rW |Ti3 mo o--cnmq-in^t-a)o>o t-rym-sru-ivof-cocTio r- cy m^-irno t-ooo^ wma-mioNto 

r: ,1. ,_,_,- ,_ 000000000000000000000000000000000000000 
000000000000000000000000000000000000000000000 



OOOCOOOv 00 

o O CO o o 00 

Ot-OEQOO 00 

OOJOOOO 00 



000 
o o 

*- o o co cm in 
C\J o o o 00 



o mc-<< Q o m^rt— 

OOOOOt-'-'-'- 

000000000 
000000000 



ca c\j in co ■< ca a 
t- ry ry (M cvj c\J ry 
0000000 
0000000 



364 



CO O 
• CO O 



E-- M O K 



cu e- : 

S a c 
o o c 



i- 




fcd 


5= O 


t ) 


£- 








.£. C= 


CU 


1-f E-< 


Cd O 


I/) 


O X 


J &. 




cu bj 




u. 


S 






CU 


f-« CO 




2: x 


W fcj 


{> 


3 G= 


O f- 


o 


03 £- 



0= O Q CC O 

Q «=: <C Q E« c 



CUE- ' 



: 3= H : 
■3 w 



3 O Cc; <c J E O O, l-f O O I 
-Hocc'SMJE-'^: ee o; ; 



O 


£U 




CO E- 




LJ bj 








co e: 




O H 




O 


c* 


U3 W 






Q 




S-t 


cc e: 










w 






CO O O 








a J 




a. a 


» 


O 




< dj 




Ct, M 












Ha,(-, 


-J O 


=Si 


£- fa. 


x f- 


co 




CU £1, 








UJ 




CO 






cc 


(- 




M O 













X O CC H « 



— E 3 f- 






; m a: «=c x - 



:«<s<Eii- 







O 


to 




U5 






n 


M 


-3 


UJ 
CU 




a, 






:•: 


« 









!_) 


55 


T- 





lOQi-Koa: 



-s a _j u j o . 



QO«;D.h£ 



2 ? 0o0ooooooooo0ooooooooo °ooooi 
cno *- c\j m .=3- iriyat^co cri o •- NfnsirnDt-ajwo'-iMmq-iAuD [>co cm 

1 mm iniriiAlfivOiDvQi£iU5uaiOio\Qin r— r — t—t-— t~-f— f— t^-i^-t-.cOcDCOCOCOCOCOCXJCOCOC'icriCriC.i.- 
aOOOOOOOOOOOOOOOOOOOOOOO 
300000000000000000000000 



- — _w~ JOOOOOOOOOOOOOC 

- ■ ^* - m '-i-^ ix 1 w 1— ■ "^ w i^j 1 — iv 1 ■ 1 ^j" la vo i>~ co ct\ o ^" c\j m ^r in \q t^— co cx^ o *■■" oj c 
000000000000000000000000 — ">-~ — " 

OO00O000OOr~-'-*'-''~ , ~"— — ______ 



JOOOOOOOOOOOC 



« w a « w w a 

o o 00000 O 

o o 00 00 o 

inrnot-ornoo*— 00 o io< 

wuJotnooooruoo o o r 



in >~ lijf-co momUNQQi-Qawcot 
£*3 cm f-cacyojT-wmt-auMQQfocM' 



■ in co C7i «s ( 



QEuO*- W«3Ch<Ot.i 



TiOOiQO 



CO a; O, tij £i, ir- c\J 

000000000000000000000000000000 000 000000 

3000000000000000000 000 000000 



OOOOOOOOOOOC 



365 



O 3: O z: 



; w MOD O 



3= u 



, cc t-i o o. q o J 



> w 



o 



> < «* uca e xaDQ. c 
: ts en h < an kmzm * 

EC «* H iii x ts o u D 

i «*: o H cl.cc <<coii-a: 

E-* o ;<= ^h UOCuO 

10 j«o tB tt, ac 

H t" *< »-• O U CC U« -ft *H C 

IHWH «S HH Id to F" 3b e 

. £= > U O. E-> EC £U JWOWOS 

K*SMH^3 *S O CJ fc- O O 2 E 

> O O « n X E-f — . ._.... .~ .. . 
lU-OOtuK CO 

. ._ .- K 



sa;n 

£-<■<■» 

2 el, a 

o *» 



cc » 

Kb.9 



^ t~ OJ 



Q - O E [Q : 

3S O. H o E ( 

EC - CO «~ E - 

w <c x «: E a: * 



<C CQ • 


ca t- oj nj 


E- < 0= S <C W £s3 


<- „ + ,_ + 


O W OS M E-f t-> Q 


£- X X f*J E-. X O 


O 3 <C ED E-« <C 


B.HH a EC H CQ 


O M -CO O i-t =£ 


-w v- - <c — o 


CO <C >h < EC o i~i 


X - - _3 .. „ -o O O X 


E E m m — a; 


Mjar-sxr-JOfntnmeQiH 



O 2 I 
3 M Q [ 



)UUCOCdJJ^OCO^-J-JMh 
W CQ 



ooooooo ooooaooooooooooooooo OOOOOOOOOOOOOOOOOO 

cr^ o\ cr> cr* c^ o o oooooooo'-'-'-'-'-'-'-'-'-'-wcuNWtMmwwtMwmmmmfnmmmfnm 

O O O O O •— r~ ,— «-«--t-i— *-.-»~*-t-t-t-t-*-*-*~^~*-t-*-t-«-»-t— t-t- ^-r-r-r-T-T-T-r-t-t— i— r- 

ooooooo oooooooooooaooooooaooooooooooooooooooo 



o o o 
o o 
*- o o co m oj 
ra o o o o o 



o o o o o o o 
o o o o o 
roi-OOT-oOT- 
rooooruoooj 



o o o 

o o o 

o o o 

o o o 



QUOUQ' 



o o t- ru 






o o o o 






<-Hu5 CMUliJO 




CT* O^ 


E\i -.O VO IT» O JT o 




O W 


QDQNQtoQvOtn 


m 


mQco 


BQQfflldniQOO 


o 


o a r~ 



^inio <Qo w mtnt-co 

CO CO CO CO CO en Cn CT> CT» Oi C7> 

ooooooo oooo 

ooooooo oooo 



<£3Ci«C\J=rf-<W*-.=TCO£QW 
CTi (7* CTn *=i =S =C <S =S CQ CQ CQ CQ EQ 

ooooooooooooo 

ooooooooooooo 



*- ixiomowomifnoc-tD < 
0000000.0.0.0.000 
ooooooooooooo 
ooooooooooooo 



366 



t. M >H 

> oa < 

) CO OS 



I EC Cq £ 
:OfHE 

:snc 



< O K W f-t 55 EH 



-JreQXXMXO 



Eh O CM [ 

* tQ i- i 
H X O ( 



£-* a 

O Q Eh 

as ■< =5 

fc« &J X Jh 

: o -J lauidK 

< «l < W < !m !m< 

• cahcjcamoh 

; W re a. M 

3 O O U W _3 X 55 
] Q M Q CO 

< E-" re e-< e-> ct, x 

■ EHHWZMM Hi-CM^tO'- 

:WOJHXXOWw o a « n 
lOCKOCntOCOOtoaOOOCi 



toon <uias: 




re 


O tO 


cqn-^^reEtaw 






tO » 3: O 


UQ«<rewo>. 




sr: 


W 2E Eh 


wsscccgbsomss 




w 




q m < re < o m 






re o= sex 


55 «j: w -j ss 




CO 


Q -J O Eh 






o 


a fo to <* fo 


Eh < o < tO H 






■* W O Eq > &, 

(tf 3 E-H 


O W 2ZJHU 




r> 


HE-MhcOQE-'E-' 




* 


XXEn Jt-W 


[>i<zq^z; <z 


w 


H 


< -3 re < w tti o 


o\>ehmm«:<hehm 


> 




K<OOHO 


« -aJOOCKOKWOO 








awKfcojEHoea. 


CO 




*C < CO CO 



>h re 


to 


a, ra 


re 


55 


re 






Ed 


n 


fcH 


H 


ft. 


a. 


to 


K J 


x 


EH 


w 


a 


H 


VI 


X 


<s < 


a. 


to 


> 




t0 


o 




:j ss 


m 


M 


o 




re 


=-. 




o < 


O. 




X 


re 


u. 


o 


o 

to 



r- CM 



X M 



t\J 



03 



z re X CO 03 CQ o 
mBUUQE-iEHZ 



o x re : 

z *J : 

»t- 55 * 

x a m i 

O CO < ( 
55 X X 



: X X X « 



=5 3= O OS re < -^ i 
re0355O3<<S.J«< 33 t 

- -»»»re » «Ht s *< .«« 
j-3o^ix>4re~30Mjre o x = *j - - 
xxcDXMM-a:xmxwreon<3:cQ'<cot 



55 re « «: 
w o re re _3 
re cq < «c x 



MxxxxxxxxxxoiaaatKcQccEerewriatacio 
Enu[i]iiiu[d[i]Ei]U[i][aEi < a. k ]JOvinoi ,, 3coa<<<<<Q. 

>H •• 

KO O 

HO *- 

SO O 

m £-• eh 



X -4 X « *-3 

a to o jo. a oo -j 

QDQQQQfllODaQO a <S O Q Q a« re 



OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOQOOOOO 

o «- eg (n^-m\o[-co o\o »- cm m-'irno t~co en o *- c\j m^r i^\o t—co en o *— cm rn .=j- in vo t— co en eB rWm^ in 
T-^7-r-t-ri-r-i-i-NW(vNc\iwNi\iWNmmfnrnm(nfO(nmro3'3'^3'3'H.3 =r 3q.i i fiir l inifiuiin 

OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOQOOOOO 

oooooooooooooooooooooooooooooooooooooooociooooo 



o o 
o o 

inoo wauwQ 
Woo a-rainotu 

q «c t- t— q cn(HofflincrioiOi«-OH 
oojooiw oomowcy-' --• — 



o o 

o o 

o o a 

o o o 



ai"- en m r- Oi O O D i 
(MUOMOOQIkUI 



*&' 



HO O 

O o 
i- o o co oo in 

NOOO O O 



0(VJino3(MaQfcii-(03U\iDt-a3Cn<QtiJ(\Iy3Cn<QW 
OOOOO OOOr- t-t-t-t-,— i-T-i-.-i-(MCyC\iC\JC\l C\J 
OOOOOOOOOOOOOOOOOOOOOOOOO 
OOOOOOOOOOOOOOOOOOOOOOOOO 



* in co cq a cq o 

'3f*i m m rn m (^ a- 

o o o o o o o 

o p o o o o o 



367 





eo 




W 






Q 














<- 








o 


Id 




T- 










Cd 


Em O 


Ed 




CJ 


Eh 


w 




E> 






CJ 




CO CO 










O 








o 


EC 




+ 










M 


CO EC 






cm a 


O 


o 




-J 






< 




CO to 










< 










a 




EH 






X 






Cd 


Cd 




P-* <s 


CC 


0. 




P» 






EH 




CO Cd Cd CO 
CO a: EG CO 


u 








Eh 




Q 

5= 




a. 


a -- 




55 






■a: 
EC 


o 

Eh EC 


Eh 

o 


O 


C- 




EC Id 


W tn 


=5 






CO EH 


w 


a 




Cd CJ a Cd 


Eh 








ss 




» 




EH 


CO 




E 






EC 


tH X Id 


55 


Cn 


O 




EC -J 


E-4 M 


O 




as 


nzo 


o 


w 




ec cj o ec 


o 








Cd 




O 




X 


Eh CO 




Cd 






ea < 


55 Id C-J 




Eh M 






<c cet 


a; 






N 


Cd Id 


< cc 


e 




a < < q 


£h 




to 




E 




C~ 






55 Id 




-4 








Cd 55 


En 


=5 


CO 




< 


M Ed 


6-t 




>•* 


cc E ee 


ft, E-. E-< 


Cd 




cj a 




Cd 


Id 




Id 








a 


Cd EC 




Cd 






O tK 


E K 




S3 S= 


CO 




S5 E- 1 


o = 


Cd 




-3 


cj id O 


CO 25 X 


-J 


X 


« EH Eh «C 


» 


Eh 


>1 






O 


Cd 






E CJ 






fH 




Eh O 


Id O o 




O 3: 


Cd 




M 


a* 55 


-J 




« 


a J6. 


a. td 


Cd 




S5 5= 


Cd 


cd 






Cd 


o 


EQ 




re 


Cd O 




t*. 


=5 






J t- Ci, 


CO 


CJ O 


EC 






M 


EL, 




as 


-S Id 


b* == 




Cd 


W Id Id Id 




-3 


bj 






-3 






O 


►4 < 


CJ 


O 


Id 




t- CO 


Id 


CO 


Q 


CI 




X EC 


EL. E-" 


E 






Eh 


m a. 


Id 


O « 


<a E E = 




0* 




o 


O 




Eh 




Du 


Id 






S 




+ to 


n. Eh 




EL, 


a 




Cd 


£Z 


O 






>-. H CO 


E 5H 


P» 


Eh O 


EC Id Id J 


EH 


E 






EC 


EC 


CO 






>H 




X 


Cd 


H 


X Cd 


HEW 


0- E H 






Id E« 


3 O 


CJ 




Cd 


< td Id 


ODB 




Eh 


« J _J <s 


fd 


O 


O 


Cd 


Cd 


o 


C3 O 


O 




«s 


Cd 


J 


55 


Cd EC 


td » Cd 


>4 


D =3 




o 


cc 


03 O 






> 
co 


aaH 


o m Eh 


CO 


<- CO 


•s id td > 


O 


CJ 


o 


t-J 


N 


In 


E EC 


EC 

Cd 


> EC 
CO < 


Cd 

►4 

CJ 




(a 


o 


a cj 

= a 


O CO Eh 


CQ 


CO 3 


EH Eh 


O E- 

Eh Id 

co a 




5= O 


«s 
























C-J 


&d 






CJ .J 
**.4 


o 


*- 



Eh Eh : 

-J ec cc f 

X < <C 



< Eh -3 -< ^ < -3 Eh 

«..-} EC -J X X 55 ~3 X - * IXC 

M X <S X < — H<EH<OiN<l — W«S< 



; ^ H 



3 to cjcou _3 q< cl, cccoccco CJO CJ 

HOQQcccczcR»sscio^ooao*cttoa3«oaoao:cQcjcjcjocja»; 
a.jjO"3HTa,Hijjo6 1 aiJu*3>!jn.ixjfl.jow .j; .4 _j _j m o 



CJ =5 - 

cc a s : 

-3 M O 



oooooooooooooooooooo_ _ 
losm o^o »- ojm.=r in vo t-m cnoi-wcia invo t- 

")\OvO*J3vO»£)\0>JDVOfJU> t— ■ t— t— ^ t-- 

jOOfir-inflj-ii—ii— ifir*t~~ — — 

O O O O O O 



OOOOOOOOOOOOi 



uiuiu<ui<uiovu}\ow«wujw r-r-r-c-c-t-c-t-SNCOcocOcORlcc'iOco coco 

0O00000OO0O00000000000O000O'- , '-'- , '— " *-» « 



_ _ _ oooooooooooooo 

o\ot- oj ma- i/iu3t-wcno'-Ni r i=r invo t-ajwo *- 

OOOOOOOOl 



co co co co coco cjioicncT* cr» cricytcri _.„. _ _ 

uwuuuuuu i_j'_JU'_''_/i_Ji_Ji_'i_Jui w JLJi_i uOOOOOOOOOOOOOO OO t— t— 
OOOOOOO0OOOOOOO0OOOOO0O'~''~ 1 '~ , ^~ 1 '~•'~ 1 '~ 1, ~ , '~ , '~ , '~ 1, ~''~ , 



3000000000 



nco inot— cjeji-csacdcoCti t— cjcoiw t— in *- t-cs 

3QQCnC\J<!|>Q^< e-CdOCQtd 



uc~comf ini_Jr~t-Jt-J' 
-carvjoj*-Edmc-cjcjf 



-=rcyt--o4ca CM--T- 



t-coHoaino«in=rinwoacnWirot-co<uawu.Ncn u\coo>o q u t. t-w 

H/;r^j3'3'H;intfMfiinirnninir>iny3vo«3vovO'Oio\o«5y3t-t- t^ t--t--t~c— c— t--coco 

OOOOOOOOOOOOOOOOOOOOOOOOOOO OOOOOOOOO 

OOOOOOOOOOOOOOOOOOOOOOOOOOO OOOOOOOOO 



3-insco 

CO CO CO CO 

O O O o 
o o o o 



368 



=0 -3 

W CL. 

O M 

*- o o. 
+ « 
a a. 



a 



u 



<S E-. >. 

X O 

-J w s 



J =5 x W ea 

c m Ed co 

UUHW 55 E-« £ <x 

■«; 5= O. .4 O til 

£-*D < 55 ^ CQ H 

u O O =5 E-< E-« =5 W 55 

3 E-« CJ M O fc, =3 -I M 

iiK^SBS O Cd a, 

"swooso a -. 



3 O 



O E-* 



Cd 



Edu • O 55 

N > Cd E M 

OO* ' W -3 

E- S W H OJ 

otdo&Jw ucamo 

53 Cq 55 > < Oi eSE-iWW 
O O -3 » 55 55 E-* E-* E'- 
en -US X .--^. 

" — a Cd w 

Q E-* z o s a > 



Cd i 



w 



Ed 



o a 35 £- 

ss a o 
o w a « 

55 Cd 



W O ■ 

=5 W ,, - 

M O US X O 
J20< ^ <S to 

>-.>-( 0<JCOKM 

aacDooowcuoa. 2; 

KB; CO CO fc< H <fi 



E-* a: e-« > aHzoaa>M as k co co fc. t-« 

Utm<OWKHH2OOOOni0UWHaH O W 

OSOWO«<SO(*-M5=2:3£:tt.E«4NlM= 3£ « O O O 



a; i 

H (K ■«, 

<s a 

>» td 55 

£3 -4 «fl 

55 O CG 



O CO o o 



X! x; x X X X t 



; S* X X » J - * 

SZHHIHIIdQ 











t- X > w 


Cd t- 










hHH > 


> -n + 


W en 








<K 03 O 


O CJ X X 


Q K- 








«: a, a, e 


E ffl M H 


E-> X 








-O w 


•so- -*-- *-- 


-J X K * 




X 


X 


N O - 


«, >x X - - 


X M < «C 


-3 


n 




•J M 

„3 O 

O td 


en M M X _J 



O, O 


uoow «a:a,co quz 


O. 55 


KK2DOiHoaaaQaoz"5 


«S W 


HnMO J -70a.a. l _ij t j t j<MCj 




E-« 



_j O a. a. • 



c\j Cd 

<C O K E-" <r- 

»W OD- Id 

^-> E CO O U 55 Q C 

J - -O - H 55 



00 a « j >jwa< 

<QW_jCiQaQQaociciQ'a:aa.<=30> 



ooooooooooaooooooooooooooooooooooooooooaoooooo 
ojcnj^- i^ia f-cooo t-cm en.^- m «s t— co cno »- cm mamioi-ffl 9^ 0r T cy ^?^ lf !!* £> t* -000 ^ »~ w m-st tn 10 t— 
oooooooo*-*-*-«-»-»-»-*-*-»- 



ICVKMWWlMNWmO 



000000000000000000000000000 



JOOOOOOOOOOOOOOOOOO 



■> o 00 

o 00 

3 =r o o 



a a a o a a m 
a a a a a a u 



aaai-(=iM3a\Qootnciao 



•Sat-hioOOOQb.Nt-OQWmDiri'-fflt-O 



<sowooj=r>X) cnfflOomiococ\ttlQWCt,<-m 

OOOOOOO OOOOOOOOOOOOOO 
OOOOOOO OOOOOOOOOOOOOO 



incocri'Scqci T-my3tn<S03td{\ltnt-<!QKlCnO'- 

0000000000000000000000 
0000000000000000000000 



369 



~3 H 








n 


<c 


Jh W 




ee 




UJ 




M -= H U 


:m 






SS 


_3 


f- 3 Z -a: 


a; 


H 






~i 


OD1 


E- C_> EC 










W U O W 


= m ■< 






O 


CJ 


=3 CJ 


Z3 u 




o 


51 


E- 


h w 2: 


o z 


s: a. 






Q= CK 


w _j -j a 


O M CC 


o 


tfcr 










O D- 




H 


H Cu 


= =3. H 5= 


H 3= W 


U X 






CO CO 


o o ** 


W O "J 


I n 


O 


O 


Z 


OHHK 


a z o 


=fa 03 






S- < 















+ CQO 

r- J O M ' 

J + JHWH t 

_j W U] CG K o t 

w n >h u "-o w ; 

wowcc + 3 X as » 

s aa u. -3 Mot 

E h a u m o to 



Z3:a_3<i:Qii-B:totq: 
QOId JH £_...-. 

<t a. u u [i. «. w 



f_ a. Ht (-i 



t- H 


o 


O O 


x 




X 




cc 


El« &U 




Ht (-i 


EG £-. 




O 3 


O O 


E- CU 


o o x 


03 X 



a w -s- a. 



w 


ra 


cq 


o 






•=c 


i- 


s 




t- 




M 












UJ 


21 


■* 


1: 


s> 




CI 


o 


o 


C") 


s 


K 


X 


U. 



O OS M Z> 



\£> »- —1 
t- E-c U 



- -t-> ^ — o 
2XW W 



E-4 o <— > 
a: s- — o 



1 2 *S «C -^- « 



*~+ Z — • * 



. 


_3 


...1 


f!l 


It] 


sr. 


J 


X 






C3 


X 


X 


(J 


O 




X 




a 

EC 

o 

E- 


■=C 


















W 05 



EC Q W O • 



lareEazceceE-'oooeaaoccEaoo.aw-s-e 
JmJOWm-d-s 11,0,0. j<n.on J J jOh- 



; uu a o- u u 

l_J-JUOKJJ~3<D-Q-4M~J; 



oooooooooooooooooooooooooooooooooooooooooooooo 
o3oiO'-[\|(ti^i/i\dc-(000'- rj ci^- inva t- ai co f- r\i m ^- ifno C- co ct» o *— (vj els' irno c- to <t\ o >— oj m 



OOOOOOOOOOOOOOOOOOOOOOOOOOOOO' 



lOOOOOOOOOOOOOOOO 



aoH wqww QDWoaaitiwa'aQtqoN'-oiomfnoiiir-oj'-a'-t-rjt- n a 

io cms u tJ o oj ^ru^^comoUiOCMrnt^^CQQC^T-rnvnc^^caoWT-ojfniru^^o c~-<s 

wwwbjwc^tu [s J [fEt.[i J t&Ci.(i.ooooooooT-«~T-T-r-T-r-T-ojcyiMnjcyry ru ry 

OOOOOOO OOOOOOOT-T-*-r-T-r->-'--T-T-T-.-T-.-T-T-r-r-,--T-T-r- t- r- 

OOOOOOO OOOOOOOOOOOOOOOOOOOOOOOOOOOOO OO 



370 



- f- 


-J 


ce a; 






O H 


7-, s- 




E CO 


-i o 


a; 


W M 


J (K 


£-1 


£ X 


m CC 


co 


a, en 


C <C 


Ui 


b+ 



<= 








■a; 


W CO 


EC 




< 




UI CO 












tfi 


J £-■ 


U] :>-. 








co 












in 


U3 7Z 


is] £- 




u; 








"* 


1 


O 


m 


< 






^ 


"* 




-i co 


z 


CU >4 


O 









t- z 


w 


CT 


LU 


IM 




•X. 


o-= 




■s; 


^ 


^-. 


O 


IJU 














< -1 






H 




S-i 


U. 




<c 


„J 






CO Oh 








irf 


s 






ttl 


a, 


■=: 




co co 


i- 


;■= 


:* 




M 8- 


CO 


EC 


CO 


(/) 


~] 


;>-c 




Ui 


< 1 


: ) 


n 


O W 


td 








u 


a: 


E O 


O 


:a 


K 


s 


a, 


E- O 


"= 


i. 


u 


m Q 


£- O 



i-. Hj a, co cl. co 



: a, co> 2 w o 



....••• -O CO - 

- " • 55 Z - .J 
1 u - — s 



IHUUQt 



;tos:[i.coO'a;Es;2:: 



Q L0 X 

ZJ Id -a! 

<OCl" EG "•% 

CO O O E-" EC O -J 

>h 2: co o s -s cq x 

- -o^ < o - -•— 



ce 


iH- 


O 




in 




<c 


CO 


a. 


CC 


t ) 


n 


" 


>« 








u 


^ 


EC 


to 


O 


m 


<c 












a: 




. 




. 1 


I— 




-J 


us 






>-< 


t/j 


-J 


UJ 


CK 




. s 


u 


LC 


X 



:io =ti 



_J o z u w 



j cc co j j „] j 

H^XXXXXXXXXX QQd:<aQQQQKKQQ<Q<CCQa. 



000 00 000 ooooooooooooooooooooac 

^ririvo t— co O >— cm rojq- Ln^o^-co 00 1— cxjmsr in vo t— co o\0 *— rvjrn- 

cncnoi 0101 «-«-*- »- t- t- i-i- — »— cm cm CMCMOJCMCMCMCMCM mmmmmrnmmron^a-j^rs^a-a-a'^ 

r _ r _ r _ r -. T _ 0000000000000000000000000000000000000000 

000000000000000000000000000000000000000000000 



*> m * o » * * 

3 O O 000°30 O 

3 O O OOCEJO O 

3 O OO CJO^O(0Ou33 O 

3 O OO «-OCMOOOO.O O 

301i<\0'- CJi W £~_cO *- Q Q r-QOUh-D 

J O 3- O CM t— CQ CM CM O. O CMUi-cnt— o 



000 
o o 

T~ O O C 



w cm in 



000000— •- — T-i-r-T-i-cMcMOJCMCMOJ m m m en m m 
00000000000000000000 000000 
00000000000000000000 000000 



371 



9 Q ffl 19 9 



~J W 
[d a 



C^ 



3 y 3 w ^o < : 

i u O n wii- q ' 

- <c >-i w n a- — i 

en s -z a J 3 I ■ 



1 W « >-. X £-< 

x a < 03 as 

h ^ < _a m < 

: ono- *-• 



s w » 



j « 



t a = s a o os 



. -I a, o te E- a. x x a 

HO JKIU O- » £*« OS » 

k - 2S n o .j t-< u. o a 

«s h m - -a- to o 2: » 

f\J - (K *< -J >t w - n - w * 

.- n ■* e X m :£ ■< x •=: E » 



x a 

(E W 
E-t * 

WW 

a 

H W 

O m 

m a 
£« a 



o o c: fr-i 

o sm CO o o E- a. 
ro*=: s; co o n m 
-j - -a a, e^ 

-lid Jwwzrc 



9 W CJ 

W 3 

a M to 

• £-i H 

a 3 co 

a O 3 

» ET 

a ISO 



w » 3 

WOK 

w S Q 



KX OB 

to cc H w 
O o W a 



£-■ m > to 

Ld Cd CO <C W 
> O J CO H 



r- W !"• W 

» to Ed w 
U3 3 U a 

MIX* 

o a w a 
j < w 
a w 
as to hi a 
O ~3 > w 
a. -j «* a 

*- o a 
I co a 



o q < q a • 



_J OS W 

i Em H E-* a 

; m e: X a 

hw u» 



UKH a 
; < Em m -j a 



a: x x x 

co f/i CO co ex, 

SOESQQClOQCClXO 



GS OS 



W Eh 
=C OS 

- S •< 



OOOOOO OOOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOOOOOOOOO 

Ot-cm m=r in >ja t— co enc- wm^in«) nwc^o »*n o *- ojrn.=riri'X>t--cQt>OT--ojrnirin\£)t--cocT'0>-c\j 

in^iniAinin LnmininyavO'jDvO'JD^ovDvoya^'— t—c-'-'- t-t-r-^-r-t-r-^^curyajcyaiaiwcvrvjfno-io-i 

OOOOOO OOOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOOOOOOOOO 

OOOOOO OOOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOOOOOOOOO 



« w o a a a 

o o o o o o 

o o o o o 

OincOOOi- OOOtuO 

oo£nOOc\j o^rotno 



a a o a a a 

CO o o o o o o 

Boo o o o 

D3 O O *- O O O 

O O O C\i O O o 



ill o w^t-< iu >- mvoco 

ma ^- a- ^ ^ rr in uM^in 

OOOOOO ooooo 

OOOOOO ooooo 



O »- NiffflBHliiO'-m 
OOOOOOOO*-'-*- 
OOOOOOOOOOO 
OOOOOOOOOOO 



372 





f-* 








H 


n 


Ul 




O 


o 






US 


f- 


v; 


o 


>■ 






EC 


VI 




o 






U 


o 








o 




u. 




o 












11. 


n 




li. 


! ) 


1:1 














FH 






IS 


a, 


E-t 


IS 




u. 


H 






X 


o 


2: 









M 






o 




H 




O 


f- 






3 


H 


n 




to 





U 


to 


f > 


I ) 


o 
















a 


O 


° 














tr. 



o u 
to O 

M -3 



£-< '0= Q 

CX ti] Q =5 W 

t-< fc3 [t. >i S Cd W Z= 

55 53 k. EC UJ M o 

O. 3K f-> J H Kl 

a cq<co< e-< w 

><H OOSM < fr- 

ee; tt. £*« E-* tj a >h 

O H W O « t-HHOHB 

CO *-t O Q W CO M O 3 CO t- S* 

HOHZ JHOUHOWNO 



to « 



co 



u 



CO O 






O 


O — 














<c 


~J E E 























22 cr> ~J 






: > 




«S M CL, 


< 


T- 


E <S — - M 



w o 

;n n a: cu - <=; 1 

-a O 3: Q ( 

c a. w« H E-« •■ c^: 

CO 3 M * COS "3 ■ 

E- E-t X * M W - ' 

o]B)H» SIX JK 

i-i n x 10 a. • {tj t 



IU J JmJ 



*— cc 


1- *~» Q= tq 


CO E- 


O W Eh H 


M CO 


CO HlflMt- 


X M 


O M xHH CU 


E~< X 


cax 1- x x »- 


X - 


- - X - _ - 


53 


J t-J EJ 5= -3 m 


was <e sm--E am 



10 q cc 00 

Z3QCU0-iOCXiCV.QCiaS 

a■«:'-^-^XCJ■^-lJ•-^ , - | 



OCCOOOOtiJs'-fKX* 



^wcq n* 



X X X CC 

CO CO CO U U CJ M 

333 QZQQCQKUaQQQQ 



oooooooooooooaaooooooooooooooooooooooooooooooo 

iria-lfUDNWOiO-Wffl^ ITt yD ISOD 0\0 r- O — (M M^ llUDt-iD CO t- CM m =T tTlva p-£OCHO >- t\l mq-ir\H3 

m ^ M(Ylfnfncn _ r;T _ r _ r _ I .- r - rir - r - rir ,in.--t- r-^-T-T-T-^^-r-oj ojninjwcMPjmniNiTimmcninmm 

fiaoQOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 

oooooooooooooooooooooooooooooooooo««« — «« — « — «"« 



lOOOOOOOOOOOO 



a a tt o « * 

OOO Or-OlK 

O O CO O O t— 

o 00 cvjo moooo 
o 00 =r«— .=r o o o to 

iin'^tsmwr-NQocaa t- .- r- q 



000000000000000000 
000000000000000000 



o «-aj(nifls< Q u omtnt-<Q o 
ooooooooo--'-'-T-T-»-nj 
0000000000000000 
0000000000000000 



373 



U3 



U CC X u 
OO'E H 
H < £- O CO 

5= W W CO H M 
W O CO M to O 
OBHSHM 



i CO t 



O » C 



a: 

a w o e-t j o 

H as h os a* £-. 

CO O CO < CO CO 

M £-1 M £-. m u 

xw i W Q tc 













o 




o 


O 


















a 




Hf 


cc 














(N 




a 




H 


as 














>f 




a 






M 


















9 




t-« 


s 














0= 




a 




O 
















cq 




a 




OS 


Q 




W 










<C 










;= 




o 


















EC 


•=; 




^3 














a 




o 




















» 




U. 


to 




S» 














a 


til 




fd 


_1 




W 








OS 






=2 


to 


W 


<Z 




a 








OS 




a 


M 


w 


as • 


55 




















» 


O CO 


H 


ti3 


□3 6-i 












a 


n 


J 


W CU 


o 


to 


•* a, 






S3 






a 


o 




Q W 


H 




fr* til 






»H 


< 




a 


OS 


> 




EC 


ca 


£-• U 






m 


H 




a 


OS 




O O 


O 




O X 






CO 


(-, 




a 


Z3 


m 


t~ W 




H 


as cu 






■=c 


O 




a 


CO 




CM Q 


to 


to 








pa 


EC 




a 








o 


w 


K Q 












a 


U 


tO 


- O 


J 


J 


H W 




W 


<c 


CTi OS 


a 






o r- o 






to 


E-t 


j 


£_ 


S~t 


a 


«J 


m 


CO CM 


a: 




CO < 




<£ 


X 


Q 


a, 




H 










W CO 


H 


E-, 


05 


55 


t-i 


a 


O 


a 






to 


o 


O 


O 


OS 


l-i 


O 




OS 


o 


- o 






J co 


OS 


CK 




OS 


CG 


a 




M 


O CO 






■a: as 












a 




H 


o^ — 


OS 


w 


> tj 












a 








K 


GJ 


H 












a 




E-. 


o - 






CO CO 


Ed 


>H 








a 




O 


H O 






n 



E-< Q =3 0> 



H OS 




m 




OEh 


5= H 




a 




h m 2- 


0- 55 




n 




E-. a. 


O. 








w w S 


td ~J 








t'^HW 


-4 CO < 




it, 




< •== O J 


ma a 




CI 






<C O M 








CO to <c 


WHO 




H 




=3 52 ^> H 


CC Q H 




CO 


£* 


< < W C 


<S 2 OS 


1:1 


M 




ckHo; 


> M O 


a 


J 


w 


E- E- .J > 



E-< "£ x ; 

3 £-< as t 

M O OS t 

as tc <c • 

-x >i x >h x x x : 



(EE<Ol 



,ja J a.a,E-'OE-'t-<f-«E-'E-<a 
OQQQ-SOOOWaMsXXXa 
jjjjuo,a,a.ctif-Hwaw» 



xsxks: a: x x J J 

to co to co to ootoco a-n j jcwa. 

0.0.0*0,0-!.'"" 



J^4JHtMO,a._J^J! 



Ci< < O W [JJ 



oaoooooooooooooooooooooooooooooooooooooooooooo 
t— cd oiOi-tMd-TifnoO'- t\j rn^j- m\o t-ff> cno <- im m a- ifi ^ c--oo oiO*— ojro^inxot— en ct\0'- cm ro^riri 
mmm^as-sa^a'-'-'- «~T-r-T-T-,r-.-c\jt\jc\iC\i ojrycy cmcmcm fnmmcnmmrnfnmm^riT-=r=r=r^T 
oooooooooooooooooooooooooooooooooooooooooooooo 
oooooooooooooooooooooooooooooooooooooooooooooo 



o o o 

o o o 

o o o 

o o o 



o o 

o o 

o o 

o o 



o o 

o o 

o o 

o o 



o o tq td 



CUlftvO ChU IhOi-CM 

c\ic\jc\jc\jc\jc\jrncnm 
ooooooooo 

ooooooooo 



o »-t\jmmc~.(T*Q i- m m t— ct> o >- cm tnvo oitq 
o oooooooi~t-»-r-T-r-rvjtMrjrynjt\j 
oooooooooooooooooooo 
oooooooooooooooooooo 



374 



hh J X O E-< *< O CO CO H 

^ w ra w <;=*>. ej 

sa ca <c aw a; h u cc n x 

M H CCOO^DH OS 3 33WH 

WO) K 200fc-K JW <S W Id Dq a. Q 

-je«^ w e~- 2: «< « ocj^wsaxH 

> E £d fa« >■ M a; CS E-< H 

Ci]Cl3 M H f*. K O £1* 0= ■=; U. O W fcj 

BCO. WSMO E- <D-Hf-«Ktia. 

oos om e- to £-* ea u x to o o p> x 

6- H O SOOcoa:WWWJOOli!E-'E-<'a:3 

WWca Mo.oo==:soJOc_)o&:totntoCQ 

... .- .- .- — .- „J h O • — — — — •- •- — — 

1<W J 



m 

< s —» o — 

H ll, ■- =T « 

O H fa* + »~* O H O 

w *- o tn x x cdHii] a, m 

OiQO CK r-~ M H QOQ H o 

- -E-toO - --— *— -« -XJO f- 

hCJXO -XH - - _J -_J --KXXOS-iXJUt 

H Q H EC CO H Q IJ<IO.iaid — MHKWMXCO" 



JC3QQCCaja,C)QQQ3:--- ------- ■ ■ ■ - - - 



a, * 


en 


to 


in m 




O 


o * 


« 






U 






111 


t/) 


o * 




X 


£K ce o * 


n 




co w s .* 




II, 


33 CQ - * 




(1 


SEX* 






3 O O * 






a s 2 * 




lil 





< 


U. 


> 


« 














£t- 


K 


O 


















O 


OS 


cq 


CO 












CTi 









H 


CO 


• 




o 














S3 


« 


* 




cq 


Q 


X 


ca 


Q 


ca 






W 


















X 


O 


















» 






« 
















s 








* 




















o 


* 


x 


a; 


S 








CO ■ 






fa] 




CO 


to 


CO 


CO 






H X 


:« 




EC 


« 




3 


3 


3 


Q 


Q 


S < 


CK 


E-> 




* 


a. 




Cu 


a* 


►J 


J 


3 CC 


E- 


M 


















O EC 


55 


X 


-J 


* 















OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 

>X)C— cooo i— c\j m =r inioc-aj cno i- c\j en .=3- in *o [-co o>o>- w w^o 1- oj rn^r mio f-aD 010 «— pj m =r un ijs r— 
^^■^^rirvinu^u^iniriu^or>^ii^vo\o\o*4D'X3v£)vovOvD^ot~ r ~-t~-£~-t--" — """ *"~ T-r-*— *— 1— t~*-aj ryojnjoj ojcy cm 
0000000000 oooooooooooooooooooooo 000000000000000 
00000000000000000000000000000000000000000000000 



a o mint-" 1 ! o w 03 e~-<3;q worn^rmi>D*^^J Wowa- wmt- 
CMmmrnmmmm^i'ir 33-3 ^r inLnininminininvovoy3\o»jOw3 
0000000000 000000000000000000 
0000000000 000000000000000000 



O — cm n-i^r vo 
000000 
00000 o 
000000 



375 






o o a O CJ ( 



j a: t-* e-. 

3 E-< o a 

a a » 



o £- 

t3 CO C 
=& O M C 



S « E 



S X U O H CO W Q 

O O CK CC KH 

IflOHOHOHOn 
.-.- .WHWHWE-t&J 
O CO CJ CO O CO OZ 






: « o w o o o 



CJ <= — a Q ; 



cj o o a 

; a k cc a a "-a o : 

J H O *"3 H M Q J : 



O.P.fl<0<hQHHH* 
IQQQQOOOOtdaMaX* 
IJ J J Jfcftfl.D.«IdHWH» 



M W 


tn 


M 


o 






JO'-m m 


O CC 


k; 




ffl 






< + + + <= -f 


Q 


ri3 




» 






s X x x -x 


cn a 


H 


CO 








<S W H 1H ■— . H 


o < 


liS 




a 






-_ v_^ *_^ JM _ 






C) 










J — . 


*s 


CC 








H <C < =C *-* < 


<C X 


« 


LU 


a 








a m 


<! 


S-t 


« 








o — - 


a. 


m 


Si 








o 




M 


e 
















:e 


rr. 








It! 


a 


CO 




Q O 


a x 




a; 




3 


n 


a a a a a a 


« 


f- 




& 


a. 




_] j =s ■«; J J 


a ^< 


H 


-.1 


a 








2 a 


X 


~3 


01 









oooooooooooooooooooooooooooooooooooooooooooooo 

cm wmm(n(n(nmmfnmm 3 4-a3'^33-3-a'^!finin'-'-' _r " _,_,-.,- *- *- c\j w ai pj cj cm ai (y ryrym 
oooooooooooooooooooooooooooooooooooooooooooooo 
oooooooooooooooooooooooooooooooooooooooooooooo 



CT\CQOUa>- minus s o^< nau t-!\isnvocji<fflOQ 

OOOOf-r-T-^fr-i-^r-r-r-WaiNWNnjWWW 

oooooooooooooooooooooooo 
oooooooooooooooooooooooo 



o *- rnc- < O. o **■» vs 

OOOOOO*-*-'- 

ooooooooo 

ooooaoooo 



376 



4 COU 

5 Ed H X 

3 m fci ck 
c a p* as 

=5 Z < 

* a* o 



O 3 
E-t O 
CO OS 



in «io t~i» 
+ -^ + + + " 

X r~ X X X C 
M + M M M ■ 

» M - « . h 

•a; v_- <s <j: <s ^ 



a a a 
a a a a a i 
< j _j <= < . 



o 


Ed O 


u 


03 O 




O ■== 


M 


H M 


Q 


W Q 



03 03 
O 03 



tt 03 td 

* a > 
a Q3 o 



- O (HvO - ' 
» + + + " - 

i x x x m > 



a a 

Q Q Q Q I 

•J •*. < J . 



+ + -— 
x x iT : 



ico -Oa-co -<Ua-io - 
■ +--*+ + + *--.+ + + ""» 
SXinXXXvOXXXC— 



|Q Q Q Q O °- 

IQOOQaClQQQQC) 



Q3 EH 
3 03 
O Ed 

w a 



03 03 
Ed Ed 
Eh £h 



to 



w 
w w to J 

J O Ed 

re q x 
O o Ed 

C0 O K 



J to 



to _3 * re Ed Sn C 

X X Si < -J < c 

KK » Ed Q3 

03 03 * i re. - 

«=e <s * a> < 5 



* Ed 

Ed x w to H 

*J 03 w £-• <s; 

a,hQHH« re _] ■ 

O Ed Z M 2; «W WCO: 

a, re Ed N id * >zc 



Eh O E-< O 

ss =: eh 

O Eh S O 



a w 

Ed « 

> m 



to * 
M * 
O * 
Ed » 
re * 
a 
-3 * 



oooooooooooooooooooooooooooooooooooooooooooooo 
*— oj m .=t irno r— ca cr> o r-wci^ in vo r— co cr>o t- cm to .=t in *£> t— co o o o »— fy m s- tfi >^> r- co cri o «— cm m .=s" in 
rntnrntnfnrnrnrnnn^iTir^T^T^-^^Tir^rLnu^tnininininininirivO'-*-" *- r- *-.-»- t- *- r- cm cm cm cm cm cm 
oooooooooooooooaoooooooooooooooooooooooooooooo 
oooooooooooooooooooooooooooooooooooooooooooooo 



vD t«- W ifl ID E~-Ed\OVOt~Edi 
to t~ NCOCO t- NCOW r-c-i 



~ £T w into moscDio w^\o t- 

JOOOOOOOOOOOOO 

3C~-Ed\a>X)[~-Ed\0\Ot*-ld^£>\C) t*- *~ 
3 C— r-03(D ^ t-CD CD t-N coco C— Ed 



QQaaQaaaQaaaaaaaaaQaaaaaa QQ'-f 

QfcjQQQti4QaciCr.QCjaii.QCiQE1.QaQtt.ClQQ fc. E*. U. O 



OiUtiOJlf\OOCQ[i]t-^[^c:QO( T l\OCMJli<OJ in CO EQ W i— ;a-f-0-!<S 

t- *- t- {\i oj cucyt\irornrnrntria - -=r=riT=r-H-ir*iniriinLn\£) msvo vdvo 

0000000000000000000000000 0000 

0000000000000000000000000 0000 



377 



3S X S 

M Q 

H2U2 

«* w a o >• 

■Z. t-l <S 

M h O H rc 

CO £-* X £- < OS 

£d CO [d 2: <C 

CJ Cd H X HC 

M Q Ed £-• CJ £~ 

l« O CO 



K JKWKH' 



IZQDUUI 



a: a, a. t~. 



£- o S S 



ZU [i] 


s 


Id 


■a: 


U U H 


O 


» 


O 


w 


£- 










o 






« 




:s 


S-* 


2: 


M 


H 


m 


Cd 






W 




E- 


M 


M >■ U 




Q 




Q O CO 


CQ 


CQ 


U 


CO 


CO 










&- 








Cd 


M 







E- 






> 






:> 




CO 






















w 










£d 






a 


:s 


J 


0= 


H 




CO 


a 


■a: 










Cd 





Oi CO 
















EC 


CK 










cc 












w 




CO 


O 




CO 






CO 


a 


H 







































a 
a 

■a 


o 
o 
cc 
CD 

CO 

cd 


III 

0= 

o 


e- 

cc 

o 

CO 
cj 


O 
t-J 

i-K 

EC 
O 


O 
a: 

CO 

w 


a. 

EG 
UI 

H 

CJ 

X 
CJ 


a 
q a 
Ul a 

> a 

to ffl 

to a 
cc a 
















O 
















o 
















EC 






J 








w 




M a 














<S £d 


J 








Cd X - 






CM 
















CO J 








a, 




cc 


fc« 


H a 














EC K 


X 








a n — 






O 
















3 




a 


3 














co a 














Q Id 


CT> w 


o 




























■a: 


<z 






E- 






w 




m a 










CJ 






OWJX>i ->t - 










J 


X 


£C 






X 


J 


£J CJ 






CK C= 




£E 




o 


O 








CJ 


id 










t-J 


IDQXHHaJHH 


Q 


*-t 


t~i 


M <S — 


X 


H 


■a; 


M 


>-* 


w 


X 


q to 


< 




q a 


a 


a 


o 


11 


" 


-^ 


11 


[d a 


oa 


a 


X 


"^ 


"^ 


«s 


72. Ul 



X X X X X X X 

COCOCOCOCO CO CUCOQ t 

oonzaoaociaooaoei:; 
a.a.a.Q.a.ja.jja. a. < ~j j k 



iscucua*a ( Q«a.aiHQ£- , t-' 1 < 
:-300000O0£d;a>-<2< 
iQCua.a,a,cv.a,a.cc id£« Cd s 



CC S5 

a td 



x x x x J 

co co to co < 

OOOSQCGECt-' 

a«a,cua J _aoTK 



ooooooooooooooooooooooaooooooooooooooooooooooo 
\o t~ co ey> O *- eg na'ifno t~co 00 r-wmj must— eooio r-o>-N m^r irno t- co a-vO*- cwm^- inusc-ra CTi 
txicycyrufnfnrnrnrnrnrnrninrria-a-a-a'ja-aaa'iriAin'-'-'- *- *- 1- *- »- r- t- c\i oj CMt\irgcMt\jojc\iC\j 
0000000000000000000000000000000000000000000000 
0000000000000000000000000000000000000000000000 



oacdQu,ofc.Ln-- 



UDQQQQQmQOQQQ.'-*-*-*-' 
tuQb.OJQT-U.£t i a[dQCJfc J l 



UQUb.t 



000000000O'-'-'-'-'-'— >— cyc\jc\ic\JOJCyc\JC\i 
0000000000000000000000000 
0000000000000000000000000 



O «- C\J m^T ITi v£) 

0000000 

o o o a o o o 
0000000 



378 



CO w 
H CC 



a: a. s; w m 
< <* a: o 
x a: O O w 

OhOBEE 



ho<c m 



c re c 

o o : 

£- t- : 

to to c 





o 




EC 


n 


ce 






EC 








X * 


<c 


to 








a 


to 










<z 


E". 


CO 


























< * 

EC W 

EC tt 

■=: * 

-* 

r~ * 
Q-. « 
S * 

- * 


tc 

EC 

w 

Ed 
EC 


a 

w 

CK 

to 


CO 
EC 


to 




* 

* 

* 

* 












» 




EC 

EC 










<=s in 












a 


to 


H W 


X 


H 


E- 




> 


* 












CK 




< -~v 


sn 








^r - DJ vo 












tf) 


u 


O * 


<C 




Ui 


Is] 


<c 














CC 




O -J 




o 






vo — o o 












V*. 


■^ 


O * 






K 




Ul 


















to X 


<c 




W 




-J - <c 












CC 


EC 


a * 


a. 




=E 


<c 




m 














en 




«; 


IK 


u= 




tiJ EG _] K 


-J 


ls! 


1 > 








1 1 


W m 






lc 










( i 


lil 












Q 


Q 


Isl 

W 




Q — ' x a 


X 


Q 


Oi 






w 
tsi 


CO 


* 

m 

* 
* 


a 


EC 
EC 

CO 

H 


a. 

O 
s 


O 

H 


CO 


» 
m 
m 
m 
m 


m 


*r 




X 


M 




a) 








j 


(1* 


O. 5= 


EL, 


u. 




H 


£3 


h- 


M 






in 






tsi 


m 


to 


CO 


CO 


t/1 


01 










IK 




n 


es a a t 


o 


C) 


n 


w 








x * 




Ul 






(K 


m 




,-> 


:■■■) 


r) 


;'") 


£J 


u 


a o 


n 




J 


a. 


J _J <C Q 


ti- 


a. 


u. 


u: 


Csl H 


LsJ 


u * 




:> 


u: 


i- 






a. 


a, 


n. 




a. 


_J 


-1 


J j 






*= 




















a> 




s 


t-> 


*-i 


J 


» 



















OltCUOOOO 






U u e: 


r«i 


O <H ~J ttj tt. 




O 


ca n. 




CO CO iju Is< 




H 






CO CC H E-. M t- M 






HKU 


C> 


W W W E-. CO CO 




O 


CO O > 


to 


KfflldldCslOIilO 






D[-< 




ozeohoho 


X 




EWW 


i: 


<zw 











EC CO i- 

O - EL. 

CO X O O 2 



OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 

o »~ cvim^rinu3 i^-coct\o»--c\j ro^-iriO"— ai m^ mvo^cocT>o t- ojm3 , in>x)f-coaiO'-'(\jrns:inu3t~(o cn 
fnonrncrirnrnrornrnrnj3-iT^riT^r-=r r - T -- *-*-*- ^. t- t- ^-,-oj c\ic^c\j cxjojrycMojry mmnmtnmmmfnm 
oooooooooooooooooooooooooooooooooooooooooooooo 
oooooooooooooooooooooooaoooooooooooooooooooooo 



co cn<m a fa om3-mt~too\«: 

ooooo ooooooooo 
OOOOO ooooooooo 



o '-c\im=r>43 cncQis, o •- mint^ uiffloo-- 

OOOOOOOOO"- — r-r-r-r-^r-NPJ 
OOOOOOOOOOOOOOOOOOO 
OOOOOOOOOOOOOOOOOOO 



379 



; a o o os 3 w 

* a os 0= hok 

: <: 3: s s 0= u 

3 O 3 U] w E- 

z: uj us w ;£ Emto 

:hhh 3 Hzwho 
:zese;[i!D:Ot330[ij 
sajuso^oas-aaas 

: E W3 O fa £u H O 

UJ CJ is, tu CO <ii.a 
« OS £" E«)-*f-Mo HE 

:u xf-i n v] -so o 

1ZWHHOHOQQOH 
- .- .- ... ._ ._ ._ .» ,_ ._ ... &j 



« H <S W 









a. 







OS 









a. 

a: 

<5 


OS 


H 






US 


m 


=e 


O 









i) 





0= 






u. 


F-* 


E- 








H 


X 


X 










Ul 


w 


O 


UJ 




fil 








S 




>: 






E- 


f 1 




UJ 


CD 


O (a 




« 







E- 


tr* ID 


U3 




<= 


<s 




K 




u. 


J 


J 




£-> M 


£-" 


H 


U* 


a. 




S E-. 


H tZ) 




to 


W 


H 


m a 


W Ul 


O 




n 


O 





O E-< 


O 


CJ 


a 


04 


a. 



a. 


OS <s 


U a 


f- 


w 


W IS 




Ln 1Z) 


as a a 


O 


UJ 


UJ a 




M E 


W > a 



- E-q =7- 2 Q f 



OS £- O « 

OOO* 
O O 0= 1 

1 X Q E E -i s 



; W tsl UJ * 

HE- E-> H a 

K O S W * 

J W M *H a 

3 O >h O O W 

C Q, CQ D-> £s3 * 

3 11 tl Ki 



— o o m o 

-] OUioO t- 

X (Z) o 1 cq o 

— E OS - ~ O 

H<<N JB3HESHIIQ' 



I -s O O O *■ 



to co c/] to -J 0.0 a, a. a* a. E-< Q 

r>33=3Cict:ir<-QQ3Ccoooou]s 

O.B.fl.n.JO')UJ<H f iQ,D.fl.n.lKa 



oooooooooaoooooooooooooooooooooooooooooooooooo 
o f- nj fo^ invo ota 00 •— w ms ifi o t- <M m^r m vo t— ro a>o ■- t\j n^- irno so o> o ■- w tnq- inio t-tn 01 

0000000000000000000000000000000000000000000000 
0000000000000000000000000000000000000000000000 



^md wu wii-r- m in t— < o w o *- 
cm c\j oj cu cm oj c\jrnmmmmmm.=r.=r 
0000000000000000 
0000000000000000 



OOOOOOOOOOr-»-*-«~r-T-r- 
OOOOOOOO OOOOOOOOO 
OOOOOOOO OOOOOOOOO 



380 



<£ E- O O 


«* E O 


as x (Ju £« 


f- Mh 


o w 


(O CJ 


E5 E-t X 


X -SI J 


OS O M 


IdK JI 


o o s 


JKO. 


6« £-• CK 


ca <s co cs 


6, 63 


<OHW 


HH< Hfc. 


h a t»4 


CO E CO 


a: co 


w o o e: 


as <c Q a 


HfflO< 


•a; Ed S <£ 

a: jhk 



JOCj-E^ MMMc 



Cd « f 

x E-i 5b as c 

M E-> O W E » 

as < os E~> 63 O ; 

•a; a. ED O E" t 

CM -=T CO £-■ S-" Q Q3C 

a a 8 ^ «S O i 

XXX t-t 63 E-. 63 < 

63 63 63 iw :z OS 63 DSE 
QQcamno^sQot 

*= is 2 O E-t t-t Q H I 



co CO 
E- O 
3 W 



63 ' 



m os 



- CO . 



J K 63 CO 

3 W O 63 
a --o os a. a. 

KCHHOEE 
3 MMHDa 
E-h EC O CO « CO 03 
uo •- •« -- •» •- 
OS 6. 






OS 







63 


a *> 


tt 


Ui 






m m 


63 a 


a 


H 


F-< 




E-h 


s» * 


a 









n 


< a 




<= 






£-. CO 


co a 




us 


0= 









a 




EjJ 




ce a. 


co a 


a 




f- 




63 


os a 


a 


n 






E- S 


63 a 






=fi 


a 


CJ 63 


!-< a 




Ul 


US 


UJ 




co a 


63 61 







f/i 


OS OS 


h a 


C3 a 


«S 


:tt 


n 


•=: 


a 






1 ) 




35 CO 


63 a 


<C * 


•j 




X 


O It 


ps a 


-3 a 






M 




a 


a 






OS 


*— >H 








us 


f-t 


•SI M 


J a 


a 










<£ » 


>< a 




_] 








OS * 










a 


E-. a 




to 


•n 










63 




X 


-■ a 


tt] w 




US 


X 


OS 


f- a 


a 




O 


m 


I-. 


m a 



XXXOOBSOODS 
HHHQCQn\Off!W 



30 J^XXXXOX' 

:n<IKHHHHIDH: 



OX<X Jt 



a- --' •=: >h 

- „ -M X >H 



x x a: a: 

CO CO CO CO CJ 

CUEUCUCUJCJM-3 



COD- m/]OiOD D Q .-J 

3OQ0SCQ=3OaQQQ£i*£ 



3Q<c000063QQtdClSS 
3<ua,a,CL.cuQsjjcoJMi-( 



0000000000000000000000000000000000000000000000 

OT-ojfn^T invoc-o3tJiO'-c\im^in\o t-aDt^O'-cymq-ifnaf-co cior-i\tm^w\ot-cooio r- tum^ ifi 
,_,_ ,_ ,_ ,_ T-^-r-»-T-cMt\iC\icMC\iOJt\j c\ifuc\i mmmmmmmmmma-^sa-^ira-a-a-atniriinininin 
0000000000000000000000000000000000000000000000 
0000000000000000000000000000000000000000000000 



CVJ •~CT\CTvO\OOiOOC7iO'— .3- 63 6. f- f*1 CO 

,=T 63CM0JC\IOOOOOO63 O t-Uit-N IM 

^if^LnaQQQoQ'-^^aLnQaao^ooT-QQQ»-*--^cTi\£>amaaQ 

.... -, ,_, 636300.QQOa0O(*«OQ6306«UOO.O6«C>U. 



63 CM 03 £\J 6- 63 



c*« o 63 a a a a c 



or-ojminchUUON(niot-o\<:uiaaojint-<tQli.rvia-ifliot-cO'<QliiW3 
000000 oo»" *-*-*- A *- 1— T-r-cyrvicyruwfywmfninfornrnmmfna-s- 
00000000000000000000000000000000000 
00000000000000000000000000000000000 



381 



o: x 
c: a 

x fa* 

a 

Ci] o 



3 f- 

^ m u, m 

QCOQ 



O O O O 

in in in tn 
o o o o 
o o o a 



o o 
o o 



)U Oq-.fflO 

- j=j- m in in cm 

- 03 fc fn ^ o 



O O O f 

c— c— c— £■ 



-int-int-t 



^ it. in t— in to t 



voco oiQi-inaiar-m 

=r=r q- ^ iTi mm invovo 

oo oooooooo 

oo oooooooo 



E~-cqEi J mc--oattifn[~-to(i,fnt~ca[ti o-ic— P3tt«mt--oa&L,mf-oaiij m f- o t, m f- a 

oooooooooooooooooooooooooooooooooo 
oooooooooooooooooooooooooooooooooo 



382 



O W 

ra o 



m cm o 



re auo 

u 2: £-< o, 
o u 

w q < 2 

=C fc, < w 

wk hxo; 

I/) o o o 

Da £n a CO 

H 3KO. 

W K U HD 

o e-< ec to cq 



* 


S 


CC 




a 




* 


CO 


















O 


CJ 




a 




* 


















* 


M 


to 




w 
























Eh 






E- (H 




* 


















* 


<C 


s 




«< £•« 
























O 


W 




U M 




* 


















« 


O 


s> 




CO 






















<« 


_J 






-3 O 




m 






















O O 


a. 






















« 


Eh 




IK 






m 


















* 




E- 




O 5= 


Q 


m 



















* 




■a; 


N 


<£UW 


m 


















EC CO * 


tu 






CO W 


t> 


m 



















(O W * 


O 


w 




CO « 


<c 










-j 




CU 






2: IS * 




CJ 




w a 


to 


m 








X 




CO 






a, a. * 


CO 




J 


E co 




m 












Q 


tj 




to to * 


CO 


to 


O 




CO 


m 




CJ 










m 





a am 


W 


to 






K 


« 




ca 


as 










m 






m 






w 


« 






















2: 


e: 


33 as t* 


* 


















m 


Jw 









to 




















M X * 


<C 


CO 






1-1 


« 


















-J EG * 


-3 




to 









EC 


X 


X 












HH» 


a« 


<c 


w 




w 




to 


to 


to 










CJ 


M K * 


CO 




E- 


x 









z> 


» 


0= 


a; 


Q 


k: 


t-< M » 


M 


a. 


«* 


cc 




* 


a. 


a« 




J 





•~3 


j 




* 


Q 


CO 


a 


E- 


-4 


* 



















0000000000000000000 
O'-Nrti^invof-cooiOr-w m^ iri vo t--co 

0000000000000000000 
0000000000000000000 



OO OOOr-T-r-^-^-T- r-r-^-^-r-T-r-r-T-T-T-r-r-r-r 
OOOOOOOOOOO OOOOOOOOOOOOOOC 



o •— rym^r tr» t— co 
00000000 
00000000 
00000000 



383 






3 a 
o o 

PS Si 



2KEhH 
» =3 » O - 

h O o O a 
o o o c 



S-i H t 

so: 
O a. t 



CD H 

>« to 

id £■* 



JCQC0O3SXE-' £E 

o o •- — — o o w w o o 



w 



>* o 

™ _ w -a: E* 

OOto JW 

ouu 

*- a as 



-CO a 
-<S a 



x a 33 as - 



a 


«K JU 


-a* 






o 


_ 




O < t- 


mow 








O 33 




£-.£** £3 


-x * 






co 


a. a. 


=S ffl 


=) to S 


www 








S Ex. 


-J W 


a. Qid< 










M O 


U3 SI 


S EC OS * 


r- CO « 


o 


-3 






a a 


m =c o «s: 


-ca 


04 


33 




two 



a. a. 
: O O 



O £d ; 



< £-« a 

: x a 



.oua 
3 CJ tl E-* * 

hHO-W 

J 3 «: M a 

s: * — o a 

CO ■• W a 

5 >-i in .- OS a 

:ui=f-' a 

J e; x -J a 

a co tq ta <: a 



H < M «S — W « 



i qe m 







a 


W fcu 














a 


M « 






a 


£-1 [i] 






■a 


=3 ca 






a 


O E 






a 


CC 3 






a 


55 






■a 


OS 








H E 








03 O 






a 


:s a 






a 


r> =s 






a 


s < 






a 


as 






a 


E I 








o o 








a a 


CO 






a o 


q a 


« 


a 


«S til 


e: z 


{*! 




K CO 


< «* 


rij 


a 


a. 


as a: 


co 


a 





to CO c 

z> r> q « as a : 



CSDSQKO 



Id » a 

_j j os a 
i ,jQHa.HQ£-<£-'£~<a 
;OSQQ<SOOUSHSXO 
!"J J J o n.Q.« tjf-'M u» 



oooooooooooooooooooooooooooooooooooooooooooooo 
cno >- (\irna' ino- C\i rn ,=r io«3c— »oio - ■ oj ma- in^o f-coovO'-oina-iniDNCOcnor-CviO'- N ma- in 
mmmmmmffirr- *-T-r-»-'-T-'-<--t\ie\ie\!C\jc\jajc\j cm cm cm mmmmmmmmromiT^S'^r'-'- ■" *- *- *- 
oooooooooooooooooooooooooooooooooooooooooooooo 

OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 



OMDi-<(000 

o m o w o o o 



Jr-ldOt.U 



oi<su Q idfci 
o o o o o o 
o o o o o o 
o o o o o o 



O'-cviirnoco'itx} cj£tjfc.T-.=r\oco<i:Q o^- cm 

OOOOOOOO OOOi-<r-r---»-T-CMCMCM 

oooooooooooooooooooo 

OOOOOOOOOOOOOOOOOOOO 



384 



a* m td co 

M E-« WE 

E-* W W CO Q O W 

-3 cq *s « &J CO m 

O E-« o m US 

2: w o i to a a 

5= CO < £-" CO H J 

K O tUE CJtVIS £3 

O »- H «s .- w cc o 

b. Eh tt cqck* 2: o x 

a. a 3 H a k to 

H X W DCxlKUn 

d n wo: wcoo co 



Cu 



CO ! 



■-a a 



s 


.1 


CO 








w 


^ 


H 


tq 



fc. Ct, S3 

M t-« M 3= £-, 

X tq x o ta 

to o co = a: 



CO 



m t 



w 



CO CO WE-i 
cc ru til la cy 1 co 

W f-> E-« J M 

HlHK HK 

O ffl < H nj who 
W OO CJ t-i w 

ra co <scoto<«a;a 
•jehkeewooo; 

m bl Eh H Eh =3 

<tdWSWW30WW 

WOKWOOWZCK 



E ;a <o * 

«* <s • 

re 0= CO « 

■a ii k a 

U E-4 W 

OfflWB 
S v M « 



O. Gt 

W W 

Ed W 

CO CO 



HH J* 
H X -4 S> 

£d id ■< * 



XXX 
CO CO to 
3 3 =1 I 
a, a. a. . 









W M 








a co k 








-CO Cd 









O'-* a -j 








oj a a. m 









O Id E 


E 


m 


aj 


e w w 








a to * co 


cc 


GJ 


co 


OS v « CO 






-3 


w a; cq 


3 




_.: 


a H J 




a 




^azai 


Q 


-j 


t_) 


Q -4 05 E 



cy 

+ 

w x x x x 

CO - -J &3 fe, b3 ~J a ~3 w 

-~- cq o x o. < = x a x a 



CC CO X _J 

O. O, £3, fx CO d O £-* CO O O Q.hQH 

>ciaooow3QXcjxiJjE-<=>Qft:cQx:acQxowa:w 
UJD.o.a,KW<£i]<[ 1 ]o: U a,JO«WJO]UO.EUh 



SSS^ ^2S^^ S oooa0oooooooooooooooooo o°oooooo 
vON«cho^njmsin l ot^co^O'-wiri S ^ lo ^ l ooNo--njm^in«3t-a3mo^Nmjrin l os«io>oo 

22SSS 0000000000000000000 °ooooo3SooScSSSSSSc5oooo 

0000000000000000000000000000000000000600000000 



ca o c~ o m m . 
in o o o ft, o 1 

b. q m to c\j o o • 



o*-c\i m t— <s u u.^- tmoco 

OOOOOO OO*- r-r-T- 
OOOOOOOOOOOO 
OOOOOO OOOOOO 



U Ii. O ■- N fn^ ITJ y3 f- C7) *£ ID O Oi- C13 (D< B! u 

*-*-c\ic\ic\icycy oj cm oj c\j c\j cycymmmmmmmm 

0000000 00000 0000000000 

0000000 00000 0000000000 



385 



co 



W t 



z w 



a 


O O 


a 


M H 


a 


CO 




cc « 


a 


bl b3 


a 


:> ra 




55 2: 


8 


a 



M O 

a ra 



m xb: w _ - 

ra ra o 2; s o 

Ct, a ■< =: <c ra t-< 

o U2 x ec 

(K QHHtO E"* 

O EC til M ■< *-t M 1 Cri Z 
to ra > >■ E to > m 

HCQ<HWnou<so 

JiSl/JQEHOXWa. 
(H £3 ... ._ .« ... .- .- .- .- 






O 


w 


>i hi 


<s 


a a 














a 


E-« 


E-. 


EC H 




ra a 














nuo 




>H 


< S5 


2 


s* a 












w 


<c a a 


X 


ra 






<s a 













a 


fflH« 


0= 


i 


fH O 




to a 






a> ra 








a > a 







ra a, 


K 


a 








m 




> 


M m a 


K 


s 






co a 


ra 


U J X 


X 






U f-i 


CQ Q a 




t-, 




ra 


cs a 




ra x m 


ra m 


ra 


ra 


ra a 




ra 




. .J X 


E 


Cd a 














a 






£- X H 


=i 


H a 














a 






3 ^"~- 


2= 


to a 














>-i a 




to 


w 




h a 














ce a 




E-» 


J 




* 


X 


XXX 








X J 


E-< E-< a 




K 






td a 


to 


to to to 


a 






w _3 


a: X a 




dq 


> SM 




OS a 


3 


O Z> 3 


a a 


Q 


a 




w til a 




> 


n ec 


H 


a 


a. 




-] -a: 


-J 




o* 


a 




ss 


=> H 




-J a 














a 







Or 5= 


X 


—I a 














a 







cd pa 


w 


< a 


w 














a 


s a 






a 


a 










a 




M £d 


a 




a 




CO 


;« ra 




a 




EC X 


« Z 




a 




ra ps 


S-« O 




a 


a 


> <s 


35 W 






a 


55 a 


ra w 




a 


a 


n 


St 




a 




ra 


X O 




a 


a 








a 






EC - 




a 


a 


EK H 


CC EC 




a 


a 




< W 




a 




S EC 


ra 




a 


a 


M W 


s 








ra ra 


E- 3 




a 


a 


2; 


a; 




a 




» 


EC 




a 


a 


E-4 3s 


ra >* 


a 


a 


a; 3 a 




t- 03 


UJ 


a 


10H« 




z < 


=» 


a 






m a 


•a: 




to to a 


hi ra 


M 


CJ 


a 


<s <fi a 


to to 


0* ra 






ra ra a 


<e <? 




to 


a 


a 


ra m 




IC 


a 


a 




>H -3 


w 


a 


a 


<s 


H X 


b-t 


a 



a ra ec a a 



rao^oooow=^ 
a a. a r - - * —'-■•'■ 



Ua.zQ40.0.£l.t-iQHE- 

ran>~aC)OOOWK;nsi. 
a, ra ra cc w H tg 1 



0000000000000000000000000000000000000000000000 
T-T-i-T-i-»-T-i-i-cMOJt\Jt\J (MojwwojtMmmmmmtnMintotna'JTa-a'a-a-^""'" !T IT II ™ ™ I-I !T*r 

0000000000000900000000000000000000000000000=00 

oooooooooootr 



30000000000000000000000000000000000 



raoooo o ooot-oj raw 
joraaoci'-otjot-iijOjoaoor-QraoEtiU 



oooooooooO'~T-»-T-'r-«~»-T-(Mryoj(\j(M 
o 0000000000000000000000 
00000000000000000000000 



386 



h3 o t 
~3 o ■ 



to os w x t 

<s O «:hwom 

eq p- e-< uxz *■ 

jg- -J CQ H t 

cvirof- O&d X O OOt 

* * x <: =s u s to E-< 5= e 

E-< £-< td < a s: 

=30 MHlO M £U =£ W C 

« w E-< cocks Em c 

WWCdtOOWUOOOOOE 



M td HH 



—. to 

QQH CD 



X a X =G X 

CO CO C/3 CO CO EX. O C5 

a J a J Eua.jjcua.«;«3:jc 



wacaots^z-sooootdanH* 



M O 












-J 


m 


to 




Q 




M 


a m 














X 


m 




































o a 












E-* 
















EC M 












a. 


m 














03 S> 












w 
















O M 












o 


m 














to a 










K 


X 


* 


















a 




t-* 


W 


W * 














ta a 








= 


a 




m 














Q W 




Cd 


EC 




s 


Q 


m 














M S 




Q 


o 


M 


M 


W 
















> a 






CO 


E-* 




> 


* 














M H 






M 


O 


s: 


















a w 




M 


P» 


O 


W 


CO 


* 










O 


\D 






o 




c? a; 




* 












o »- 


S3 






a 






CO 






X 


_3 


X 


















CC 


* 


a 


H 




M 


X 


a eq 


S 




J 




-j 


U 




* 














« 




X 


m 


X 


EQ 


E-< 

to 


a 














CO 














* 














X 


EC 










o 


a 


X 


X 


X 








EC 


o 










W 


* 


to 


to 


CO 


et* 






o 


CO 


w 








CC 


* 


o 


a 


=3 


O 


a 


a q 


£u 




EC 




H 








a. 


a. 


tt. 


a. 


-3 


*j j 


EC 




£-< 




M 




-J 


* 














W 


M 


K 




X 




~3 


* 















OOOOOOOOOOOOOOOOoOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 
Ot-i\jrng-^voNa3ovo^i\jms^ioN«ChOT-(\imwinar-(vini3;in^^©cno»-<\im^u^ix)t-«Ch 
cm (\i ru cm cv cm cm c\i c\j cm mrommmmfnromfng'g-a-a-g-g-'-'- r-rr-r-r-i-r-r-ojcy t\iojt\jcvitMoat\itM 
oooooooooooaoooaooooooooooaooooooooooooooooooo 
oooooooooooooooooooooooooooooooooooooooooooooo 



ini^i^D'-ioini-oioiQMoiaininOa-QoQ'-'-'-i 



o r-«rninco<ffluQii:r-(nif>stocMiiuuot\im^in 
ooooooooooo»-T-T-T-*- T -r-t-.-CM(Mojrynj 
o oooooooooooooooooooooooo 
o oooooooooooooooooooooooo 



o>- m^vocMD 
o o o o o o o 
o o o o o o o 

o o o o o o o 



387 



OlfflCE 



&- a; tc >■ m H 
3 M <S E-> M O 

HiuoiiiDaazK 

5 «S M t^ tj M S 

- E-i id » co w w 
std-Joso£U[dO< 
jwoe-'owwcas 



* « ~3 

Si [d Q M 

ft == S S 

ft Hi Q 

ft £-< U =5 

ft 3 td W 

ft O CO 

9 KHH 

St IB J 35 

ft O -3 O 



S -3 O 03 

U c cu a; h 

« O O E-" O 

CJ « O li. 3= Id W 

Cd O -J Id => OS 

Qb< a. s 35 

KOWHH 

os eh td O os £-« a; 

O CO =5 _3 U 35 O 

It. O =5 — W O E-t 

-3 M Q CJ CO 

r- Q .- .- .-[J 

I «< as 



id w * 

r-q bc a: -3 ec ft 

qq o o cj causwcuwa 1 a,a J E-'OEH£-4w 

QQtE3H0SCQCqa[d-T)OO^>OOOCdKMHO 



<vox > ft 

j m <s < m 

UiiU W ft 

Q m td \o ft 

\o o m w w 

n in os « 

C~ in£d a 

' ya £-• ft 



I CO * 



I moOH 

UWJW J -Id -3 -JCUU 
PQIQXIBQIOIQD 



CO WW U 2 Q ft.0.fl.tHOHH* 

OSSOCdQ-^QCUOOOtdaiMSft 



J E-* 

td 52 
Q Id 



O O 
O O 



aooooooooooooaoooooooooooooooooooooooooooooooo 
o fftjma-invot- co ai o — rym^r in vo f- co o *- cym^rmvoc— co o\ o «-c\j m^ino t-cocno »- c\j m o »- cvi 
mrnmmm( , nrommmiriT^rjT^T-=r^T=r-=T'— *- *-'-»-»-*-*- .— t- oj c\jc\j{\jojc\jcyc\ic\jt\jrnmmrriT-*-r- 
oooooooooooooooooooooooooooooooooooooooooooooo 

OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 



oo'-'-T-'-'-'-'-'-'-cyCMMcycMCM 
oooooooooooooooooo 
oooooooooooooooooo 



Or-cymvoSffiCQUInOr-W 
OOOOOOOOOO'-'-t- 

ooooooooooooo 
ooooooooooooo 



388 











•J3 




■a 








U 






•5 












o 


55 


o 


h* 


M 















m 




a 


CC 




H 

a 


cq 


















CO 


CC 


o 


5* 


CC 




Itt 










in 






Ed 




o 




O 






















o 






o 




CC 






■J3 




a 


H 


EC 


o 


=G 


cq 


















Q. 






E-" 




a 
















O 


w o 


U 


W 




-3 










o 




td 


u 




a 




a 




E-* 






o 






< 


E-t 






t-J 


IjJ 












to 


o 


Id 


o 


cc 


i~t 


















a 


cq 


a f-< 


J 




55 


I-. 










X 


to 


CO 


5S 


E- 


cc 




a 


















»-f 


=5 


-J 


cq 


O 




M 










X 






a. 


o 














in 




a 


K 


o 






O 


a 


W 


rs 


w 










CM 


o 


H 






a 




<s 


















£-. 


Gu 




cc 


a 


cq 






o 


o 


X 


o 


O 






a 


H 








in 




« 






w 






b 


o 


M 


a 






to 




<K 


o 


cc 


a. 




a 




O 






in 








o« 


cq 


W 


E- 


M 


E-- 


!-■ 


h- 








o 


cq 


H 




X 




a 


E-" 








^o 




« 


J 


X 


U 




CO 




to 


55 


co 


Cq 






CO 


CC 




fcj 


w 






Z3 


55 








W 


a 


>H 


» 


w 




W 


o 


w 


O 


w 












CM 


E_ 


t-< 






o 


w 








a 


« 


[_. 


CQ 


G> 


CO 


E« 


a 


cq 


CJ 


cc 


E-< 




o 






CC 








a 














'81 




















E-) 




to 


en 




O 


O 


a, 


u: 


a 












o 






















CC 






o 


X 


55 


55 


CO 




a 


O 


o 






co 


cq 




























CO 








O 




a 


to 


a: 






*•* 


E- 


* 
























o 


X 


cc 


CC 


< 


a 


to 


a 
a 




I-* 








a. 


■a 
























to 


co 


< 


o 


E- 


o 




a 




M 






ax 


W 




























o 




55 


E-« 


o 




a 












u 


a 


























to 


to 




O 


55 


-3 




o 










X 


























X 




►-} 


o 


CC 




CQ 


a 


<c 


&3 


CC 




O 


u 


a 
























cc 


c— 


£_. 


cc 
o 


s 


O 




a 






£-* 






a 














o 












Ifi 


o 


X 


55 


Q 


a 


a. 


a 


a: 


<2 


c_> 




w 




* 


























to 






O 






a 


o 








2 


> 


a 












o 




E 






X 


a: 






CQ 


55 


o 


cq 


a 




a cc 


W 


















j 




o 












u. 


H 




55 


^ 


a 




f-« 


«: 




o 


CO 
























H 




vo 


£-. 


-J 


O 


w 


a 


a 








55 














GQ 


b 




J 






co a 


o 


CO 


•C 


a 


=■ 


55 














to 


a 


Q 


bj 














fct, 




>* to 


to 


cc 


55 


o 


o 


M 




lu 


K 








ffi 






a cq 


=2 


■< U 


w 


<t 


fcu 






to 




X 


El. 




s 


X cc 


a 




O 




cu 


O 


w 












































M 


■=; 


Q 


CQ 


£- 








































a 




to 




"— 


-~ ' 


to 


a 






































a 



a X a 

1 X * 

tijxxxxxxxa wa 

X jcqcccqccecccccaf-fa 

ooto cu n.hQHhhhh^Ht-B«» 

Q2U3DKO;oaoMzHzazZZB2 f "- — 

_JMaa._JO-3CL.-3a.cqC" " "" "" " 



]E->_JW_J[_lWbJ[i5a tOi 



00000000000000000000000000000000000 
ma- ono t-o cnor- fum^-ini^NcoaiO'-w o •— oj (n^w«)t>.tooio»-(Mm3 
^^^^'-^^CMfurynjryryryojCMtMrnrocn^T-T-T-T-^»-^-»- T -ojt\jt\Jt\iAj 
ooooooooooooooooooooooooooooooooooo 
00000000000000000000000000000000000 



o •— cm tna-inyjco c\ffl o 
o 000 0000000 
00000000000 
00000000000 



o-rcoooa-coo oa-cotq 

OQOO'-'--'-ftlW«(M 
OOOOOOOOOOOO 
OOOOOOOOOOOO 



389 



o o o 

cm c\j m 

o o o 

o o o 



,^^,00000000000000000000000 

fU (y !\J <\1 CMCMCMCMCMCMCMCMCMCMOJCMCMCMCM 



oooo oooooooo 
cmcmcmcmcmcmcmcm 

oooo ooooooooo 

CM OJ CM CM CM CM "■ ~' "' 

o o o o o o 

CM CM CM CM CM CM 

ooooooooooooooooooo 

rti rti rti rti fti m r\i ru rt( r*t r\i r\i r\i r\i ni f\i (M tM f\l 



_ _ _ _ ______ _oooooooooooooooooooooo 

CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM CM "'"''•'"'"'"'"''''''''"'"'"'"'"' "' 

_ooooooooooooooooooooooooo 

CMCMCMCMCMCMCMCMCM CM CMCMCMCMCMCM CM - ' """"*'" 



CM 



CMCMCMCMCMCMCMCMCMCMCMCMCMC 

__ooo — ___ 

CMCMCMCMCMCVJCMCMCMCMCMCM 

O O O 1_ _ - 
CM CM CM CM CM CM 

WWWWWWWW OOOO v_- -— — _ W . 

CMCMCMCMCMCMCMCMCMCMCMCMO CM CM CM CM CM .: 



J CM CM ( 



_____.__.000000000000000000 OOCJOOCTiti 

wwwwwwwwcilcynJwrMtycywwwrywryo inin!n ' nininininin!ftlwwwD 



lirnf-m^o^TOOo^mOo^tooowmoo^muo^aaOo^ffloo^cooo 

Nmmfn(n^^3J^ioi"in^«5vo^^t~c-t-»»aia)acnoAa><<<<«Emmu _,_„„„„„ 
oooooooooooooooooooooooooooooooooooooo ooooooo 
oooooooooooooooooooooooooooooooooooooo 



ooooooo 



390 





K 


W 




M 


o 


CO 


S-. 


t-S 




w 


l-< 










ai 


f-i 


-i 


H 


o 



< $- W W til 

(HE *C C14 

: :a » to to a, o 

s; o x a to eq 



GE--fc3HaJiJHo oi 

-fSCOKICQCQCQCUWa: 

fi0=>0330td0<;! 



O 2= O O O O C 



o a o 

to CO to 

2: 2: 2: 



« CO *• CK ■■ O 

hiho, .. .. a. a, tu a q 
MHU.HXOnE>U3 
WXOOOOOWOWM 



OOOOOOOOOOOOOOO 

•-cm ro=r m\o t— ajdo *- c\j o-i^rin 
j3--=r^r=r^r-=r^r^r=r un in in in tr» in 

OOOOOOOOOOOOOOO 
OOOOOOOOOOOOOOO 



WfcO 
JT ST CM 

fc. Q fc, 



ooc\ji£>ooocnoooMooomooO' __.. . 

OWW»OIVW3-ONN3'OWNWoNlAniOOON; 



orgifi 
ootnfc*ooai*"-ooinoioomCMOOOWoo 



oojoooootu^ro 



■i-ooQomino 
-c\it\it\ic\jc\i;=r=roj 



En o o o ^ 

mo o or 

oooooooooc 

ooooooooo* 



in Qr-incMDiimt-cnQi- inc-,tQ d-minoiQ i-mt-m t- r-mino\D^ 
aDiiliawwiiim.t.l.ooooO'-'-f-r-njNftinKvmirimmfnj 

OOOOOOOOOOa*--i--i-'~-r~»-r--T~T- r -r- T --r-.r-»~T- T -.r-.-T- 
OOOOOOOOOOOO OOOOOOOOOOOOOOOOOOO 



rn =r vo to «£ ID U Qho^ 
q'^s^-a-s ^rzr-=T in in 

OOOOOOOOOOO 



391 



i-i O i- lH CM 

LO O -~ OJ J J S O 

i- (MH <<COffl 

E/} E: 3: E S K t-( r~ 

^ShXO"— CM^^TEOOf-' - 

<c -s: ~j o ^ o a a ■«; o 

CCKHOOOOOOMMO - 

<<t<iiB:a:iKUUUQQco 



in 



in 



in 



EM 



m 



.=r (M ^ cm =r •- ,=t o *- cm »~ aj — CM*-(Mcr.crvcnCT^cr»cri 
(n'-mmrninmt- -— - *-* - "" - *~ -— - *~ "*~ 

• + . + ~+ ■.+—+,-+»-+*-+«-+.-+»- + 

oxoxaxoa: -as - x -as -as -a: - x - x 
-o -o -o -oxoxoxoxoxoxoso 

XOXOXOEOOOOOUOOOtuOJj^Orx.O 

oouooocjocQOcqutaueQucQomomo 



O^OiOOOOOOOOOOO 



sea n H1303 

Q -3! O. Q Q Q Q 



]3£q3:ffl3ffl3:a3l03£n3n3 3m3 



KEOlKffiKOOUaQH 

rcwsooooooooo 



ooooooooooooooo 
us t—co o>o »- cm en -a- iavonco cno 
if\ininiriiovovO'Oio*o>cw3'Xno t— 
ooooooooooooooo 
ooooooooooooooo 



300000QOOO 



JOOQLJtJtJULja w w u 
3000000000 OOO 



OOOoOOOOOOOOOOOOw — ■ 

{n^ifivDt-tocnoi-Ojr'lirirnor-iDcnO'-wnia-iii'i'i- 

t«-t*-[~-t»_t~_C~-t--°3a3tX)CacOa3COCOCDCO (71 C7> Q* C% CTi CTi d C7* 

ooooooooooooooooooooooooc- 

oooooooooooooc -~ " --.<-.* 



o o o o o o 

o o o o o o 

o o o o o o 

o o o o o o 

o o o o o o o 

o o o o o o o 

oooooooo oooo ooo 

oooooooo oooo ooo 



0fc.01n0b.0fc0t40 



;o moootno-^otn 



10000000000000000000 ooooooooooooooooooooooo 



392 



ft. Q oOIKCqiKKP* 

MO O* *- <M & E X X H 

£c3 .- 

O 

Q<X) ^0 o cm vO CO OJ O CO OJ 

K - - -- __-_«- 

m p~- m »— in t~- in *— rn t— in 

Wio o c\j co co oj o \o \£> co 
co in \£> t— co Q - 

-=r *- cm m .=r -J in £_ m ,_ prj ^ ^ ,_ xr> _ 

+ + + + +o- - _- 

O^CTiOOOO 

-i-t-[— r-t--r~t^r-t-_ . sr\ ,— i^, ^ in — en c-. m t- 

-I'-X'-I'-X'-K JCy CO io O O >J3 co CM OJ o 

xo-o-o-o-ornm- 

Ct.oxoxoxoa:o&i«:— in t~- m *- m t- in *- m 

ffl O b U fc O U< O 6. U ft. H » 

ococomcorncofncornoo cm co \o c\i o vo co o ys 

w 



QQC3QQCSQC1QQQ Q 



o a 

re 55 



ooooooooooooo 

O^OiOOOOOOOOOO *- 

OOt-»-T-.-T~T~*-,-,-«-_ 

ooooooooooooo 



o o 


o o 


tn i— 
o o 


t- m 
o o 


in t— 
o o 


*- in 
o o 


O O 


CO o 
O O 


W3 OJ 

o o 


O CO 

o o 


o CO 

o o 


«3 OJ 

o o 



oooft,o<somoo 

ft. o a la u* 

ft.Oft.ftlfc.Wft.ftlft.WC 



t- in 


in 


— 


o o 


o 


o 


O CO 


w> 


CM 


o o 


o 


O 


rn *- 




m 


o o 


o 


O 



OOOOOOOOOOO 



mininq-mu a r~ inio < ft) ft. co t-co uo.-inoi"Sli]wmMaooirinO\QU 
aQ[ilwuwwii,ii.[«.[i.[i.fcoooor-i-r-^^^i\j(\j«iMnjmmmmmm 

OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 



393 



\£3 CO 



to « 
•<t T si 

t- o c 

(9 S'«S 
t- t- Cfl 



O O O O O C 



c\jc\j(\jcuc\jc\ic\jf\icvjpjc\jfMryc\j fury 
OOOOOOOOOOOOOO oo 



394 



The last module of the listings is the SYSTEM module. 
SYSTEM contains all messages, variables, and tables for 
the program, since we don't know its length beforehand. 

The last, and most important, table is PTABLE, the per- 
mutation table we've been talking about. Since this is 
generated completely by the program, it's simply defined 
as the last location of the program. 

Moving backwards, we find RINDT. This is a "Rotation 
Indices" table used by subroutine ROTATE. It contains the 
indices for converting from the "standard" array into 
rotations and mirror images. The last half of the table 
contains the indices from reconversion. 

Hints and Kinks 14-4 

Retranslation 
We've talked about translating from one array 
to another one representing a rotation or 
mirror image. Unfortunately, retranslation 
back from the second to the first is not 
straightforward. To convert to a 90 degree 
rotation, for example, we have 
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To take the new array and reconvert back into 
the old array after processing, we ' d have - 
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The translation indices on reconversion bear 
some relationship to the conversion indices 
(each is 8-conversion index), but this 
relationship doesn't hold for other 
reconversions ! 

It's probably simplest to establish another 
table of reconversion indices, which we have 
done in the last half of RINDT. 

There must be an easier way to implement this 
program! (Maybe you'll be the one to discover 
the way. ) 
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The GRIDTB is a table of values used by the DRAWL 
subroutine to draw the tic-tac-toe "grid." Each five bytes 
defines one line. 

The MOVETB table holds the address of each space cell used 
in a computer move. Each of the four entries may point to 
a space cell in the PTABLE so that it may be "adjusted" at 
the end of each game. 

ANALTB is the "Analysis Table." It holds a count for each 
row, column, and diagonal of the current array. We'll 
discuss this under the ANALSR. 

The ROTTAB table is the "Rotation Table." It holds the 
base three values for each of the eight rotations and 
mirror images of the current array. As these may be up to 
19683, the entries are eight "words" of 16 bits. 

There are 12 system messages at the beginning of SYSTEM. 
All of these are terminated by a 0. 

The variables are described in the comments field of each 
variable, and we'll discuss them in the subroutine 
description. 

Program Description 

Here, as in MORG, we'll use a "bottom-up" approach to 
describe the system modules, starting from the least 
complex. 

Fill Character Subroutine (FILLCH) 

The FILLCH subroutine fills a given character into any 
area of memory. It decrements the byte count in BC down 
to zero and fills memory by using DE as a pointer register 
pair. 

Delay Subroutine DELAY 

The Delay subroutine delays from 1 through 65536 milli- 
seconds, depending upon the count in the HL register pair. 
It is used only for large delays for display of system 
messages in tic-tac-toe. 
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Divide Subroutine (DIVIDE) 

The Divide subroutine implements a divide of a 16-bit 
number in HL by an 8-bit number in E. The quotient is in 
HL and the remainder in BC on exit. DIVIDE is used by 
BINBAS for binary to base three conversion, although it is a 
general-purpose divide. 

Base Three to Binary Subroutine (BASBIN) 

BASBIN is a specialized subroutine for tic-tac-toe. It con- 
verts an array representing a tic-tac-toe configuration to a 
base three number. The array is either ARRAYl or ARRAY2 
in the system; each is a nine-byte table, holding a for a 
space, 1 for an X, and 4 for an 0. At the end of the 
conversion, HL holds the base three number in binary, 
through 19683. The array is organized as shown in Figure 
14-19. 



ARRAY +0 
+1 

+ 2 
+ 3 
+ 4 
+5 
+ 6 
+ 7 
+ 8 



VALUE FOR SPACE 



VALUE FOR SPACE 1 



VALUE FOR SPACE 2 



VALUE FOR SPACE 3 



VALUE FOR SPACE 4 



VALUE FOR SPACE 5 



VALUE FOR SPACE 6 



VALUE FOR SPACE 7 



VALUE FOR SPACE 8 



VALUE=8 FOR SPACE 
=1 FOR X 
= 4 FOR O 
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Figure 14-19. ARRAY1/2 
Format 



Binary to Base Three Subroutine (BINBAS) 

The Binary to Base Three subroutine does the opposite of 
BASBIN — it converts a binary number of through 19683 
to nine base-three digits of 0, 1, or 2. It then converts the 2 
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to a 4 and stores the nine digits in a given array (ARRAYl 
or ARRAY2). The binary number is the "current value" of 
the configuration. 

Random Number Routine (RAND) 

RAND generates a pseudo-random number from a "seed" 
value. Its operation is virtually identical to RAND in the 
MORG program. On exit, BC contains a random number 
from through 65535. This number is used to "shuffle" the 
"balls," or space cells, for the current configuration, to 
choose one of the space cells for a computer move. 

Input Subroutine (INPUSR) 

The Input subroutine detects a key press of through 9 
and ignores all others. Tic-tac-toe uses only these keys for 
user input to define the play. A debounce of 100 
milliseconds is performed by calling subroutine DELAY. 

Display Message Subroutine (DSPMES) 

DSPMES is a subroutine to display a given string of ASCII 
characters on the screen. On entry, HL points to the string, 
and BC points to the screen position. The routine picks up 
a character from the HL pointer and then outputs it by 
using BC as a pointer. The string is terminated on a zero 
(null) character. DSPMES is only called by HISTUP to output 
the "history" message along the bottom of the screen. 

Large Character Display Subroutine (LARGEC) 

This subroutine is a general-purpose subroutine to output 
"large" characters of 8 by 8 pixels to the screen. The 
subroutine is called with A containing the character to be 
output in ASCII and IY pointing to the upper left-hand pixel 
of the 8 by 8 block to be used. 

The characters A through Z, space, "-", "?", and "!" may be 
output. They are defined in the DOTTAB table of LARGEC as 
an 8 by 8 dot matrix, reading from left to right and top to 
bottom. 

Large Message Output Subroutine (MSGOUT) 

MSGOUT is similar to DSPMES except that it calls LARGEC 
to output a large character message. On entry, HL points 
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to the message and IY points to the start of the screen area 
for which the message is intended. IY will point to the 
upper left-hand pixel of the first character position of the 
message. 

MSGOUT calls LARGEC until a terminating zero (null) 
character is detected in the message. Most tic-tac-toe 
messages are large character messages, except for the 
"history" message. 

Display Screen Array Subroutine (SCRNDS) 

SCRNDS is a specialized subroutine to convert an array 
(ARRAYi or ARRAY2) to a tic-tac-toe grid with Xs and Os. 
The "grid" of the tic-tac-toe pattern is never rewritten 
during the program. SCRNDS, therefore, only fills in Xs and 
Os in the nine tic-tac-toe positions. 

SCRNDS scans through the array from top to bottom and 
tests to see whether an X or O is present. If a blank is 
found, nothing is output for the position. If an X or O is 
found, SCRNDS calls MSGOUT with a "dummy" string 
consisting of an X or O followed by a zero (null). It puts 
this dummy string in the TEMPI variable, a 16-bit variable 
allocated for this purpose. 



Draw Line Subroutine (DRAWL) 

The DRAWL subroutine draws either a vertical or 
horizontal line on the screen. The line is drawn through 
character positions rather than pixel positions. This 
makes the screen addressing a trivial rather than complex 
task. 

On entry A contains the graphics character to be used. C 
contains a zero if a horizontal line is to be drawn, or a 
non-zero if a vertical line is to be drawn. HL contains the 
screen start position. B contains the number of character 
positions to be used. 

DRAWL first decides whether a vertical or horizontal line is 
to be drawn. A branch is made to the proper code for each. 
If a horizontal line is to be drawn, A is stored indirect to 
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HL, HL is incremented, and B is decremented down to zero. 
If a vertical line is to be drawn, A is stored, HL is 
incremented by 64, and B is decremented down to zero. 
Note that vertical lines must start at the top position and 
horizontal lines must start at the left. 

DRAWL is called by MAIN1. MAIN1 uses the GRIDTB table in 
the system to draw a complete set of lines representing the 
tic-tac-toe grid. The GRIDTB table is set up so that each 
entry is five bytes long, corresponding to values to be put 
into A, B, C, and HL. It calls DRAWL repeatedly until it has 
used every GRIDTB entry. 

Array Translator Subroutine (ARRXLA) 

The Array Translator Subroutine performs a rotation or 
mirror image translation from one array to the next. It is 
used in conjunction with BASBIN to find the new array and 
then to find the new base 3 value represented from the 
new array. 

As an example, suppose that a rotation of 180 degrees is to 
be done on the current array. ARRXLA is entered with IX 
pointing to ARRAY1 in SYSTEM. IY points to ARRAY2 in 
SYSTEM. HL points to the list of 9 indices for the 180 degree 
rotation in SYSTEM at 1ED'. The nine indices of ARRAYl are 
converted to the nine indices of ARRAY2 as shown in 
Figure 14-20. When the conversion is done, ARRAY2 holds 
a tic-tac-toe configuration rotated 180 degrees from 
ARRAYl. A BASBIN can now be done on ARRAY2. 
ARRAY1 ARRAV2 
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5 s > 3 

6 ». 2 

7 g> -f 

8 g> 

Figure 14-20. Array Translation 

ARRXLA is chiefly called by the ROTATE subroutine, which 
performs the seven rotations for finding the smallest value 
initially for the PTABLE, and then, later on, rotates the 
current tic-tac-toe array to find the smallest value for the 
PTABLE search. 

Analyze Array (ANALAR) 

ANALAR analyzes the current array to find eight hash 
values for the rows, columns, and diagonals of the given 
array. Although we've been discussing a base three value 
that represents the current configuration, the values 
actually held in the current (ARRAY1) or working (ARRAY2) 
arrays are actually for space, 1 for X, and 4 for 0. The 
reason for these values is that a simple add can give us 
unique values for the numbers of Xs, Os, and spaces in 
each row, column, or diagonal. 



Hints and Kinks 14-5 

Hash Values 

A hashing technique uses an approach something 
like this: Is there a way to convert all 
possible actions to a series of unique numeric 
values that can then be used efficiently in 
processing? 

An example from an assembler: Some assemblers 
add the ASCII characters in a symbol together 
to get a hash total. It turns out that this is 
(relatively) unique. The sum of "NAME", for 
example, is different from "START". This 
one-byte hash value can then be used in a more 
efficient search of the symbol table than a 
six- or seven-byte string comparison; this 
speeds up symbol table searches and reduces 
assembly time. 
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If the row, column, or diagonal has three spaces, the hash 
value will be 0. If it has two spaces and an X, the hash will 
be 1. Two spaces and an O yields a 4. One space and two 
Xs gives a 2. One space and two Os gives an 8. One space 
and an X and O gives a 5. No spaces and three Xs gives a 
3. No spaces and two Xs and one O gives 6. No spaces and 
one X and two Os gives 9. No spaces and three Os gives 12. 
All of these values are unique and represent only one 
defined configuration. A test can, therefore, be easily made 
for "two Xs and a space," or "three Os." This greatly 
simplifies testing for tic-tac-toe conditions. 

At the end of ANALAR, the eight hash values are saved in 
the ANALTB (Analyze Table) of SYSTEM. 

Number Subroutine (NUMBER) 

The NUMBER subroutine also helps to analyze an array. It 
counts the number of Xs, Os, and spaces in the given array 
(ARRAYl or ARRAY2). The number of each is put in 
variables NOX, NOO, or NOSP in SYSTEM. NUMBER is called 
by MAINl to analyze the configuration for PTABLE. 

Eotate Subroutine (ROTATE) 

ROTATE calls ARRXLA eight times to perform the rotations 
and mirror image translations of the current array. After 
each call, the translated array is converted to a numeric 
value by BASBIN. This numeric value is then put in 
ROTTAB in SYSTEM. At the end of ROTATE, the eight base 
three values are in ROTTAB and the DE register holds the 
lowest value. This lowest value is then used either to 
establish the PTABLE entry (MAINl) or for the search of 
PTABLE. 

History Update (HISTUP) 

HISTUP is called at the end of the game with a L (lose), W 
(win), D (draw), or C (concede) in the A register. This code 
is then put in the last position of the history buffer, and 
the entire history message is then output to show the 
history of the last 128 games. If 128 have been played, 
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HISTUP "slides" the last 127 games into the first 127 game 
positions by an LDIR and then stores the current game code 
in the 128th position. 

Memory Subroutine (MEMORY) 

MEMORY implements the "reward'Vpunishment" action at 
the end of each game. It is entered with a -1 in A for a lost 
game, a 3 for a win, and a 1 for a draw. 

MEMORY then uses the MOVETB, which has a record of the 
space cell addresses, to add or subtract counts from the 
space cells that were used in the games. A comparison is 
made for increments over 99. If the count is greater than 
99 (on a win or draw), the space cell is set to 99. A 
comparison is also made for decrements below 0. If below 
(on a loss), the space cell is set to 0. 

Main Driver Modules 

There are four main driver modules, named MAINl, MAIN2, 
MAIN3, and MAIN4. MAINl is used to perform "first time" 
actions, primarily to build up the PTABLE. Since this action 
takes several minutes, it is only done one time on each 
load. MAIN2 through MAIN4 are used to implement the 
actual game-playing. 

MAINl 

MAINl first clears the screen with graphics 80H characters 
(FILLCH) and then displays the history message (DSPMES). 
Initially the history message will be filled with blanks, 
since no games have been played. DRAWL is then used to 
draw the grid. 

Next, the Move Table MOVETB is cleared. An entry of is 
used as a terminator since is not a valid address for a 
PTABLE entry. 

Now the First Time Flag (FRSTF) is tested to see if this is 
the first time through the program. If not, the program 
goes on to MAIN2 actions. If it is the first time, the history 
line is filled with blanks (to handle any restart of an 
already executed program), and a WAIT ONE message is 
displayed on the screen (MSGOUT). 403 



Now the Permutation Table (PTABLE) is generated. The 
algorithm used is identical to that described above under 
"Generation of a Permutation Table." A count is incre- 
mented from 000000000 through 222222222 in binary 
form. BINBAS is used to find the equivalent tic-tac-toe 
array. NUMBER is called to count the number of Xs, Os, 
and spaces. ANALAR is called to analyze the eight rows, 
columns, and diagonals. 

If the array passes all of the tests, ROTATE is then called to 
find the lowest value of the eight possible rotations and 
mirror images. If the current array is the one producing 
the lowest value, a new PTABLE entry is made. The 
number of spaces in the array is then counted and stored 
in the next byte. Space cells are allocated dependent upon 
the number of spaces. The number of spaces is then 
divided by 2 to produce the initial count to be put in each 
space cell. The quotient of this divide is conveniently equal 
to 4,3,2, or 1 per the algorithm. 

If an entry in PTABLE is made, a dash is alternately 
blinked on and off at the end of the N A I T ONE message to 
show processing activity. 

MAIN2 

MAIN2 is entered at the end of PTABLE computations for 
the first time or reentered for the main loop in playing 
games. The main loop is ART070, entered from MAINl for 
each new game. Location MAINLP is reentered for each new 
move of a game. 

If this is a start of a new game, ART070 outputs the title 
message and then clears the main array, ARRAYl (FILLCH). 
MAINLP is then entered. When MAINLP is entered, the 
game has either just started or has been going on for a 
number of moves. In either case the action is the same. A 
call is made to ANALAR to analyze ARRAYl. 

If two Xs exist, the computer finishes the game in the code 
at ART102. To do this, however, it must try an X in spaces 
until it finds one that produces an analyzed value of 3 
(three Xs). It laboriously calls ANALAR after each try. 
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When the proper place for the X is found, it outputs an 
I WIN message and goes to the "end action" code at 

MAINEA in MAIN4. 

If two Xs are not present, the program then tests the Move 
Number variable MOVENO for 5. MOVENO represents the 
number of times the computer has played and is 
incremented after each computer play. If this is the last 
(5th) move, the computer plays in the only space, and then 
tests for a win. If there's a win, it goes to the action in 
ART106. If there's a draw (there cannot be a loss), it outputs 
a DRAW ! message and goes to the end action code in 
MAINEA. 

If ART114 is entered, none of the above applies. ROTATE is 
now called to find the eight rotation values. ROTATE 
returns the smallest value in DE. This is the PTABLE value 
that will be used for the search. A search is now made 
(ART120). The PTABLE value must be found if PTABLE has 
been constructed properly. After the value is found, MAIN3 
is entered. 

MAIN3 

With the PTABLE entry found, the program now must 
handle two arrays. The first, in ARRAYl, is the present 
tic-tac-toe array. The second, in ARRAY2, represents the 
translated array from PTABLE. If the PTABLE value was the 
same as the present array, both arrays will be identical (0 
degrees rotation), otherwise ARRAY2 will hold a rotated or 
mirror image array. 

ARRXLA is called to convert the present array to the 
rotation or mirror image in ARRAY2. Then ARRAY2 is 
analyzed by ANALAR. If two Os are found, the computer 
"blocks" the move by putting in an X in the proper space. 
The code at ART102 is used to find the space which 
produces the proper block, and the code at ART106 finds the 
proper space cell for the blocking move. After the block, a 
JP is made to ART172 for further processing. 

If a blocking move is not possible, the code at ART125 is 
performed. This code finds the total count of all space cells 
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associated with the permutation. If this total count is zero, 
this path is hopeless and will be deleted. The MOVETB is 
used to find the last move, and the space cell for the last 
move is zeroed. An I CONCEDE message is then output, 
and the end action at MAINEA is performed. This 
concession action will rarely happen. 

If the total count is non-zero, a random number less than 
or equal to the total count is found by calling RAND. The 
space cells are totaled until the total is equal to or greater 
than the random number. This action is analogous to 
stirring the balls in the box and picking one! (See Figure 
14-21.) 



CONFIGURATION: 



X 











X 



PTABLE ENTRY: 



46H (000 002 121) 



10 



CONFIGURATION IN 
BASE 3 

# OF SPACE CELLS 

COUNT FOR SPACE » 
COUNT FOR SPACE 1 
COUNT FOR SPACE 2 
COUNT FOR SPACE 3 
COUNT FOR SPACE 4 



PICKING A SPACE: 

1. TOTAL COUNT OF SPACE CELLS =10+2+7+1 = 21 

2. FIND RANDOM # < = 21 ; 12 

3. O— — *TOTAL 

4. ADD SPACE CELL B ; TOTAL = 1S . < RANDOM # OF 12 

5. ADD SPACE CELL 1 : TOTAL = 12, = RANDOM # OF 12 

6. SPACE CELL 1 WILL BE USED FOR MOVE, CAUSING X TO BE PUT INTO SPACE 1 



X 







X 







X 



Figure 14-21. Using RAND To Pick A Space 
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Now an X is stored in the array (ARRAY2), and a record is 
made of the space cell move in MOVETB. We worked with 
AREAY2 and then converted it back to ARRAYl by a call to 
ARRXLA. RINDW holds the pointer to the "reverse indices." 
SCRNDS is then called to display ARRAYl, and MAIN4 is 
entered. 

MAIN4 

MAIN4 is used to get the human input. It outputs the 
YOUR MO ME message and waits for user input from 
INPUT. A check is made of the validity of the number of the 
square chosen and a TRY AGAIN message output. 

When the human inputs a valid move, an O is stored in 
ARRAYl and SCRNDS is called to display the array. AN ALAR 
is then called (ART185) to analyze the new array. Only a 
human win can occur at this point. If the human wins, a 
YOU WIN message is output and the end action at MAINEA 
is performed. If no win occurred, the next computer move 
must be done and MAINLP in MAIN2 is reentered. 

The end action at MAINEA is entered at the completion of 
every game. Before this point the HISTUP (History Update) 
and MEMORY routines have been called to update the 
history message and "reward" or "punish" the PTABLE 
space cell. MAINEA outputs a ANOTHER? message and 
waits for a key press. On the key press, ARTIP in MAIN1 is 
reentered for a new game. 

Using This Program 

As in the case of MORG, this program was designed and 
coded to let you see a significant chunk of presumably 
worthwhile code. If you'd like to experiment with the 
program, you may enter the machine code by using Disk 
DEBUG or T-BUG. Figure 14-22 gives the machine code 
after the program load. There are several thousand bytes, 
but a fast typist could enter them in an hour. Checkpoint 
by saving partial results! You can do this by dumping to 
disk (by DUMP) or to cassette (P command in T-BUG) and 
then reloading to take up where you left off. 

407 



8000 

8010 

8020 

8030 

801)0 

8050 

8060 

8070 

8080 

8090 

80A0 

80B0 

8OC0 

80D0 

80E0 

80F0 

8100 

81 10 

8120 

8130 

8110 

8150 

8160 

8170 

8180 

8190 

81A0 

81B0 

81C0 

81D0 

81E0 

81F0 

8200 

8210 

8220 

8230 

82H0 

8250 

8260 

8270 

8280 

8290 

82A0 

82B0 

82C0 

82D0 

82E0 

82F0 

8300 

8310 

8320 

8330 

8310 

8350 

8360 

8370 

8380 

8390 

83A0 

83B0 

83C0 

83D0 

83E0 

83F0 

8H00 

81110 

8420 

8430 

8110 

8450 

81)60 

81170 

8480 

8190 

84A0 

8 HBO 

84C0 

84D0 

84E0 



31 E7 8A 3E 80 11 00 3C 01 10 03 CD OB 88 21 18 

88 01 40 3F CD 13 87 DD 21 A2 89 DD 7E 00 FE FF 
28 16 DD 4E 01 DD 46 02 DD 6E 03 DD 66 04 CD 42 
85 01 05 00 DD 09 18 E3 AF 11 98 89 01 08 00 CD 
OB 88 32 67 89 3A 5B 89 B7 C2 2C 81 3C 32 5B 89 
11 57 88 ED 53 5C 89 13 3E 20 01 80 00 CD OB 88 
21 D9 88 FD 21 00 3C CD A2 85 21 B8 OB CD F8 87 
21 E7 88 FD 21 00 3C CD A2 85 21 E7 8A E5 21 00 
00 22 5E 89 E5 01 E3 4C B7 ED 42 CA 29 81 09 DD 
21 6E 89 CD 83 87 22 88 89 21 6E 69 CD 7E 84 3A 
62 89 57 3A 63 89 BA 28 03 E1 18 79 FE 01 28 F9 
DD 21 6E 89 CD AC 81 06 08 21 80 89 7E FE 03 CA 
A9 80 FE OC CA A9 80 FE 02 CA A9 80 23 10 ED CD 
16 84 E1 E5 B7 ED 52 20 DO El DD E1 DD 75 00 DD 
74 01 FD 2A 5E 89 FD 23 FD 22 5E 89 3A 64 89 4F 
DD 71 02 DD 23 DD 23 DD 23 DD E5 D1 06 00 DD 09 
DD E5 79 CB 3F D5 CD OB 88 3A 5E 89 E6 01 21 49 

89 28 03 21 IB 89 FD 21 3C 3C CD A2 85 DD El DD 
6E FD DD 66 FE 23 C3 84 80 E1 DD El 21 D9 88 FD 
21 00 3C CD A2 85 21 B8 OB CD F8 87 01 09 00 AF 
11 6E 89 CD OB 88 21 67 89 34 DD 21 6E 69 CD AC 

84 21 80 89 06 08 7E FE 02 28 05 23 10 F8 18 3F 
E5 21 6E 89 7E B7 28 03 23 18 F9 E5 3C 77 DD 21 
6E 89 CD AC 84 E1 DD El DD 7E 00 FE 03 28 06 AF 
77 DD E5 18 E3 CD 5D 85 3E 57 CD E3 83 3E 03 CD 
B1 83 21 2D 89 FD 21 00 3C CD A2 85 C3 9B 83 3A 
67 89 FE 05 20 3A 21 6E 89 7E B7 26 03 23 18 F9 
3C 77 DD 21 6E 89 CD AC 84 21 6E 89 06 08 7E FE 
03 28 C2 23 10 F8 CD 5D 85 3E 44 CD E3 83 3E 01 
CD B1 83 21 3B 89 FD 21 00 3C CD A2 85 C3 9B 83 
FD 21 6E 89 CD AA 87 22 88 89 CD 16 84 DD 21 E7 
8A DD 6E 00 DD 66 01 B7 ED 52 28 OC DD 4E 02 06 

00 03 03 03 DD 09 18 E9 DD E5 2A 60 89 01 88 89 
B7 ED 42 CB 3D CB 3C 30 02 CB FD E5 29 29 29 CI 
09 E5 01 F3 89 09 DD 21 6E 89 FD 21 77 89 CD 17 

85 E1 01 3B 8A 09 22 6C 89 DD 21 77 89 CD AC 84 
21 80 89 06 08 7E FE 08 28 05 23 10 F8 16 52 E5 
21 77 89 7E B7 28 03 23 18 F9 E5 3C 77 DD 21 77 
89 CD AC 84 El DD El DD 7E 00 FE 09 28 06 AF 77 
DD E5 18 E3 AF 77 E5 01 76 89 B7 ED 42 11 FF FF 
45 21 77 89 7E 23 B7 20 01 13 10 F8 E1 3E 01 77 
DD E1 DD 19 DD 23 DD 23 DD 23 DD 23 DD E5 C3 1E 
83 DD El DD E5 DD 46 02 21 00 00 DD 5E 03 16 00 
19 DD 23 10 F6 7C B5 DD E1 DD E5 20 25 3A 67 89 
3D 07 4F 06 00 DD 21 98 89 DD 09 DD 66 00 DD 6E 

01 AF 77 21 4D 89 FD 21 00 3C CD A2 85 3E 13 C3 
93 83 CD 46 87 C5 D1 EB B7 ED 52 30 FB 19 DD IE 
03 06 00 B7 ED 12 DD 23 28 02 30 F2 D1 DD E5 E1 
01 03 00 DD 09 DD E5 B7 ED 52 45 DD 21 77 89 DD 
7E 00 B7 DD 23 20 F8 10 F6 3E 01 DD 77 FF 3A 67 
89 3D 07 5F 16 00 21 98 89 19 D1 1B 73 23 72 2A 
6C 89 DD 21 77 89 FD 21 6E 89 CD 17 85 CD 5D 85 
21 F5 88 FD 21 00 3C CD A2 85 CD 23 87 IF 06 00 
21 6E 89 09 7E B7 28 12 21 03 89 FD 21 00 3C CD 
A2 85 21 B8 OB CD F8 87 18 D6 3E 04 77 CD 5D 85 
DD 21 6E 89 CD AC 84 21 80 89 06 08 7E 23 FE OC 
28 05 10 F8 C3 46 81 21 11 89 FD 21 00 3C CD A2 
85 3E 1C CD E3 83 3E FF CD B1 83 21 B8 OB CD F8 
87 21 1F 89 FD 21 00 3C CD A2 65 CD 23 87 C3 00 
80 F5 E5 DD E5 DD 21 98 89 DD 66 01 DD 6E 00 F5 
7C B5 28 19 F1 F5 86 CA CD 83 F2 CE 83 AF FE 64 
FA D5 83 3E 63 77 DD 23 DD 23 F1 18 DC F1 DD E1 
El F1 C9 C5 D5 E5 2A 5C 89 23 22 5C 89 01 D8 88 
B7 ED 42 20 10 OB ED 43 5C 89 21 59 88 11 58 88 
01 7F 00 ED BO 2A 5C 89 77 21 18 88 01 10 3F CD 
13 87 El D1 CI C9 F5 C5 E5 DD E5 FD E5 06 07 DD 
21 FC 89 FD 21 88 89 FD 23 FD 23 FD E5 DD E5 DD 
21 6E 89 FD 21 77 89 El E5 CD 17 85 CD AA 87 DD 
El FD E1 FD 75 00 FD 74 01 FD 23 FD 23 11 09 00 
DD 19 10 D7 06 08 DD 21 88 89 11 FF 7F DD 66 01 
DD 6E 00 B7 ED 52 F2 70 84 19 54 5D DD 22 60 89 
DD 23 DD 23 10 E7 FD E1 DD E1 El C1 F1 C9 F5 C5 
D5 E5 06 09 11 00 00 OE 00 7E FE 01 20 01 14 FE 
04 20 01 1C B7 20 01 OC 23 10 EE 7A 32 62 89 7B 
32 63 89 79 32 64 89 E1 D1 CI F1 C9 F5 FD E5 FD 
21 80 89 DD 7E 00 DD 86 01 DD 86 02 FD 77 00 DD 
7E 03 DD 86 04 DD 86 05 FD 77 01 DD 7E 06 DD 86 
07 DD 86 08 FD 77 02 DD 7E 00 DD 86 03 DD 86 06 
FD 77 03 DD 7E 01 DD 86 04 DD 86 07 FD 77 04 DD 
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84F0 

8500 

8510 

8520 

8530 

8510 

8550 

8560 

8570 

8580 

8590 

85A0 

85B0 

85CO 

85D0 

85E0 

85F0 

8600 

8610 

8620 

8630 

861)0 

8650 

8660 

8670 

8680 

8690 

86A0 

86B0 

86C0 

86D0 

86E0 

86F0 

8700 

8710 

8720 

8730 

8710 

8750 

8760 

8770 

8780 

8790 

87AO 

87B0 

87C0 

87D0 

87E0 

87F0 

8800 

8810 

8820 

8830 

881)0 

8850 

8860 

8870 

8880 

8890 

88A0 

88B0 

88C0 

88D0 

88E0 

88F0 

8900 

8910 

8920 

8930 

891)0 

8950 

8960 

8970 

8980 

8990 

89AO 

89S0 

89C0 

89D0 



7E 02 
OD DD 
FD 77 



09 
77 
F1 
08 



E5 FD 
FE 01 
89 CD 
FE 01) 
F1 C9 
FF FD 
E5 DD 
06 86 
86 DD 
E1 CI 
FD 23 
l)C 4D 
2D 3F 
33 33 
30 30 
03 03 
03 03 
30 30 
30 30 
00 09 
03 03 
03 03 



DD 86 
86 08 
07 FD 
E5 5E 
23 DD 
C5 D5 
1 1 1)0 
E5 21 
20 01) 
A2 85 
20 05 
F5 C5 
09 23 



09 CD 
F1 C9 

10 F2 
1)E l)F 
21 17 
3B 17 
1A 17 
01 17 
2B 00 
38 15 
30 IF 
3A 16 
03 16 
25 17 



03 03 
33 30 
03 03 
22 11 
CI F1 
FC 79 
CD F8 



06 
68 



C9 C5 
EB CI 
09 C5 
2B C1 
00 00 
02 85 
D5 DD 
30 01 
C1 DD 
83 10 
B1 28 
20 20 
IF 52 
4D 1)5 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
13 2D 
l)E 1)5 
20 20 
00 20 
20 1)F 

19 20 
52 11 

20 H3 
00 00 
00 00 
00 00 
00 00 
00 00 
3E 8C 



30 00 
03 07 
00 F5 
C9 C5 
18 09 
87 E1 
CD 6B 

22 6A 
ED 1)B 
C9 F5 
CD DO 
10 ED 
06 09 
6F 30 
E5 E5 

23 DD 
E5 E1 
FE 19 
03 F1 
20 20 
59 3A 
53 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
51) IF 
20 20 
00 20 
20 59 
IE 45 
20 57 
57 21 
l)F HE 
00 00 
00 00 
00 00 
00 00 
8C 00 

00 22 

01 A5 
DA 3C 



05 DD 86 
FD 77 06 
E1 F1 C9 
16 00 FD 
23 10 EC 
E5 F5 79 
00 77 19 
6E 89 06 
3E 58 18 
E1 23 11 

11 9F 00 
E5 FD E5 
18 F1 FD 

86 DD BE 

12 E5 DD 
FD 85 01 

06 01) DD 
C9 41 42 
50 51 52 
03 03 2B 
03 03 OB 
03 03 03 
03 03 OB 
2B 17 00 
00 20 06 
10 20 2F 
03 03 29 
03 03 29 
03 03 03 
00 00 2A 
28 14 2A 
00 00 2A 

00 00 00 
23 33 3B 
C5 E5 7E 
E5 3A 10 
3A 20 38 
C1 C9 F5 

87 10 FB 
89 43 4C 
6A 89 B7 
C5 E5 DD 
87 79 FE 
DD E1 E1 
E5 D1 19 

01 24 FD 
DD E1 21 
23 B7 ED 
DD E1 D1 
DA FF 87 
18 F5 F1 
20 20 20 
20 4C 41 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
45 20 00 
00 20 20 
20 54 52 
4F 55 20 
20 4D 4F 
49 4E 21 
20 20 20 
43 45 44 
00 00 00 
00 00 00 
00 00 00 
00 00 00 
22 8F 3C 
CF 3E BC 
3C BC 01 
BF 01 09 



DD 7E 
F5 C5 
E1 FD 
FD E1 
B7 2-0 
10 EC 
09 FD 

02 3E 
OB 00 
FD 19 
7E B7 
El E1 
00 DD 
E1 DD 
3C 00 
7E 00 
43 44 
53 54 
17 03 
35 30 

37 33 
35 30 
00 3A 
17 03 
15 02 
25 30 
25 30 
33 33 
35 30 
25 3A 

03 2B 
00 00 
00 22 
B7 28 

38 B7 
E6 01 
D5 E5 
06 03 
E1 D1 
ED 42 
E5 01 
02 20 
CI F1 

19 FD 
23 10 
00 00 

52 30 
C9 C5 
El D1 
09 20 

20 20 

53 54 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 00 
20 20 
59 4F 
59 20 
20 57 
52 45 
20 20 
20 00 



77 05 
02 DD 
D5 E5 
E5 FD 
FD El 
07 F1 



4F 32 
FD 19 
10 D1 

28 OB 
C1 F1 
23 20 

29 DD 
FD 09 
CB FF 
45 46 
55 56 



DD 7E 
86 04 
DD E5 
19 DD 
DD El 

77 23 
C1 C9 
3C 7E 
65 89 

78 FE 
FD E1 
CD BC 
C9 F5 
F9 DD 
29 DD 
CD F4 
FD 77 



15 
65 



E1 D1 

85 01 

C5 E5 

E5 E1 



49 4A 
59 5A 



33 30 
30 3B 
35 00 
03 24 
01 2A 
30 1A 



33 3B 
30 3A 
35 1A 
17 03 
00 00 
11 00 
05 02 
28 09 
28 EA 
ED 5B 
CD 71 
F1 C9 
EB ED 
08 00 

02 OE 
C9 F5 
7E 00 
EA FD 
16 00 

03 19 
D5 E5 
CI C9 
20 20 
20 20 
20 31 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 54 
57 41 
55 52 
41 47 
49 4E 
3F 20 
20 00 
20 00 



17 03 

17 03 

15 00 

00 00 

15 00 

17 24 



35 
17 
17 



03 2B 
15 00 
09 30 
03 03 
00 00 
00 2A 

03 23 
OE FF 
3E 08 
68 89 
87 10 
29 EB 
4B 68 
DD 09 

04 DD 71 
C5 D5 
FE 04 



45 20 20 00 
00 34 12 78 



00 00 

00 00 

00 00 
8C 00 

01 01 
01 BO 
E5 3C 



23 FF 
00 00 
00 00 
22 4F 
8F 3C 
3C BF 
BF- 1 



DD 2B 

11 FF 

12 13 
20 20 
20 48 
32 38 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
20 20 
49 43 
49 54 

20 4D 
41 49 

21 20 
20 00 
20 20 
2D 00 
00 57 
56 00 
FF FF 
00 00 

00 00 
3D 8C 
BC 01 

01 09 
09 FO 



00 DD 86 

DD 86 06 

FD E5 06 

7E 00 FD 

El D1 CI 

10 FC 18 

F5 C5 D5 

B7 28 

E5 21 

07 28 04 

C1 

C1 

DD 

01 

29 01 23 
85 DD E1 
00 DD 23 

4B 
20 

03 2B 37 
03 29 
03 03 
00 2A 
00 2B 34 
00 00 35 
00 2A 15 
03 2B 17 
03 2B 17 

17 03 00 
00 2A 02 

30 06 18 
33 OF 3C 
00 00 03 
15 00 00 

18 F7 El 
OC OF 30 
21 64 00 
2A 6A 89 
FB ED 53 
ED 6 A EB 
89 ED 42 
1E 03 06 

00 DD 
FD E5 21 
20 02 3E 
CI F1 C9 
29 DD 29 
10 EE E5 
FF 2B 06 
OB F5 78 
20 20 20 
49 53 54 
20 47 4 1 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
20 20 20 
2D 54 41 
20 20 4F 
4F 56 45 
4E 20 20 
20 00 20 
20 20 20 
20 20 44 
20 20 49 
88 00 00 
00 00 00 
FF FF FF 
00 00 00 
00 00 00 

00 22 OF 

01 9A 3C 
CF 3C BF 
3C 8F 01 
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Figure 14-22. Machine Code 
to Tsc-Tac-Toe 



Hints and Kinks 14-6 

Checkpointing 

How often should you checkpoint? I'm from the 
old school - I never trust computers. As a 
matter of fact, you may employ Barden's Law: 
The more you checkpoint, the less you'll need 
it! If you don't checkpoint, an operator error 
or power failure will surely wipe out several 
hours of work. But seriously - the TRS-80 is 
much less prone to losing data than 
minicomputers of several years ago ! And 
reliability will continue to get better with 
newer hardware . 



You may also key in the source for the program and use 
the Disk Assembler to assemble and load your own version 
for experimentation. This is quite a task, but it's certainly 
possible, especially since the program is modular. EDTASM 
may also be used to assemble one huge program. 
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APPENDIX I 



Z-8 Instruction Set 



A Register Operations 

Complement CPL 
Decimal DAA 
Negate NEG 

Adding/Subtracting Two 8-Bit Numbers 

A and Another Register 

ADC A,r SBC A,r 

ADD A,r SUB A,r 
A and Immediate Operand 

ADC A,n SBC A,n 

ADD A,n SUB A,n 
A and Memory Operand 

ADC A,(HL) ADD A,(HL) SBC (HL) SUB (HL) 

ADC A,(IX+d) ADD A,(IX+d) SBC (IX+d) SUB (IX+d) 

ADC A,(IY+d) ADD A,(IY+d) SBC (IY+d) SUB (IY+d) 

Adding/Subtracting Two 16-Bit Numbers 

HL and Another Register Pair 

ADC HL.ss ADD HL,ss SBC HL.ss 
IX and Another Register Pair 

ADD IX,pp ADD IY.rr 

Bit Instructions 

Test Bit 

Register BIT b,r 

Memory BIT b,(HL) BIT b,(IX+d) BIT b,(IY+) 
Reset Bit 

Register RES b,r 

Memory RES b,(HL) RES b,(IX+d) RES b,(IY+d) 
Set Bit 

Register SET b,r 

Memory SET b,(HL) SET b,(IX+d) SET b,(IY+d) 
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Carry Flag 

Complement CCF 
Set SCF 

Compare Two 8-Bit Operands 
A and Another Register CP r 
A and Immediate Operand CP n 
A and Memory Operand 

CP (HL) CP (IX+d) CP (IY+d) 
Block Compare 

CPD,CPDR,CPI,CPIR 

Decrements and Increments 

Single Register 

DEC r INC r DEC IX DEC IY INC 

DEC ss INC ss DEC IX DEC IY INC IX INC IY 
Memory 

DEC HL DEC (IX+d) DEC (IY+d) 

INC (HL) INC (IX+d) INC (IY+d) 

Exchanges 

DE and HL EX DE.HL 
Top of Stack 

EX (SP),HL EX (SP),IX EX (SP),IY 

Input/Output 

I/O To/From A and Port 

IN A,(n) OUT (n),A 
I/O To/From Register and Port 

IN r,(C) OUT (C),r 
Block 

IND,INDR,INR,INIR,OTDR,OTIR,OUTD,OUTI 

Interrupts 

Disable DI 
Enable EI 
Interrupt Mode 

IM IM 1 IM 2 
Return From Interrupt 

RETI RETN 

Jumps 

Unconditional 

JP (HL) JP (IX) JP (IY) JP (nn) JR e 
Conditional 

JP cc,nn JR C,e JR NZ,e JR Z,e JR NC,e 
Special Conditional 

DJNZ e 

Loads 

A Load Memory Operand 

LD A,(BC) LD A,(DE) LD A,(nn) 
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A and Other Registers 

LD A,I LD A,R LD I, A LD R,A 
Between Registers, 8-Bit 

LD r,r' 
Immediate 8-Bit 

LD r,n 
Immediate 16-Bit 

LD dd.nn LD IX.nn LD IY.nn 
Register Pairs From Other Register Pairs 

LD SP,HL LD SP.IX LD SP.IY 
From Memory, 8-Bits 

LD r.(HL) LD r,(IX+d) LD r,(IY+d) 
From Memory, 16-Bits 

LD HL,(nn) LD IX.(nn) LD IY,(nn) LD dd.(nn) 
Block 

LDD,LDDR,LDI,LDIR 

Logical Operations 8 Bits With A 

A and Another Register 
AND r OR r XOR r 

A and Immediate Operand 
AND n OR n XOR n 

A and Memory Operand 

AND (HL) OR (HL) XOR (HL) 

AND (IX+d) OR (IX+d) XOR (IX+d) 
AND (IY+d) OR (IY+d) XOR (IY+d) 

Miscellaneous 

Halt HALT 

No Operation NOP 

Prime/Non-Prime 

Switch AF 

EX AF,AF' 
Switch Others 

EXX 

Shifts 

Circular (Rotate) 

A Only RLA, RLCA, RRA, RRCA 

All Registers RL r RLC r RR r RRC r 

Memory 

RL (HL) RLC (HL) RR (HL) RRC (HL) 

RL (IX+d) RLC (IX+d) RR (IX+d) RRC (IX+d) 

RL (IY+d) RLC (IY+d) RR (IY+d) RRC (IY+d) 
Logical 

Registers SRL r 

Memory SRL (HL) SRL (IX+d) SRL (IY+d) 
Arithmetic 

Registers SLA r SRA r 
Memory 

SLA (HL) SRA (HL) 

SLA (IX+d) SRA (IX+d) 

SLA (IY+d) SRA (IY+d) 

BCD RLD RRD 
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Stack Operations 

PUSH IX PUSH IY PUSH qq POP IX POP IY POP qq 

Stores 

Of A Only 

LD (BC) ,A LD (DE) ,A LD (nn) A 
All Registers 

LD (HL),r LD (IX+d),r LD (IY+d),r 
Immediate Data 

LD (HL),n LD (IX+d),n LD (IY+d),n 
16-Bit Registers 

LD (nn) ,dd LD (nn) ,IX LD (nn) ,IY LD (nn) ,HL 

Subroutine Action 

Conditional CALLs CALL cc.nn 
Unconditional CALLs CALL nn 
Conditional Return RET cc 
Unconditional Return RET 
Special CALL RST p 
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Z-80 Operation Code Listings 
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Absolute location 17, 52 
Addition, assembly-language 

112-122 
Arguments, for macros 64 

general 21, 22, 98, 111 
Array storage of machine 

code 110, 111 
ASCII characters, general 22, 

23, 142, 185 

working with 135-158 
ASEG pseudo-op 66 
Aspect ratio 189 
Assembling, hand 86 
Assembly, location counter 

43, sequence 49 
Backspacing, on input 145 
BASIC, interfacing 94-98 

address computation 105 
Binary/hexadecimal 

conversion 15 
Binary search 173-176 
Buffering, characters 295, 

296 
Breakpointing 83, 91 
Bubble sort 180-183 
Carries 117 
Character positions 184, 190, 

191 
Characters, line printer 220 
Checkpointing 410 
Checksum 77 
CHR$ strings, embedding 

machine code in 106-108 
CLOSE I/O call 260 



Coding 279, 280 
Command file 87 
Comment line 13 
Comment field 13 
Conditional assembly 68 
Constants 42 
Control codes 142 
Coversion, ASCII 

binary/hexadecimal 158 

ASCII decimal to binary 

153-155 

binary to decimal ASCII 

155-158 
Cross-reference listing 69 
CSEG pseudo-op 66 
DATA statements, 

embedding machine code 

in 104-105, 108-111 
DC pseudo-op 149 
Debounce, keyboard 140, 293 
DEBUG 90-93 
Debugging 90-94, 281, 282 
Decimal/binary conversion 15 
Decimal/hexadecimal 

conversion 15 
DEFB pseudo-op 43, 44 
DEFM pseudo-op 43-45 
DEFS pseudo-op 45, 46 
DEFW pseudo-op 43, 44 
Delimiter 69 

Desk checking 81, 82, 91, 280 
Device control blocks (DCBs) 

247-250 
Displacement field 102 
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Display, of characters 148 

of input characters 150 

of message 
Disk Assembler 53-74 
Disk Assembler, edit 

commands 56, 57 

files 87 

labels 62 

loader 61, 62, 71-74 

macros 62 

using 70 
Disk, characteristics 235-238 

controller 241-245 

device control blocks 

247-250 

drives 238-241 

formatting 238 

signals 240 

TRSDOS I/O calls 251-263 

TRSDOS organization 

245-247 
Disk files, for Disk 

Assembler 55 
Disk input/output 235-263 
Divide operations, 127-130 
DJNZ instruction 102 
Dummy strings 108, 109 
DUMP command 93 
DSEG pseudo-op 66 
Edit buffer 55 
Editor 13, 38 
EDTASM 37-52 
Effective address 112 
ENTRY pseudo-op 62 
EQU pseudo-op 46, 47 
Expressions 48 
EXT pseudo-op 62 
Fields 12 

Flags 31, 32, 35, 41, 115, 122 
Floating-point operations 134 
Flowcharting 272, 273 



Format differences, between 

EDTASM and Disk 

Assembler 54 
Free format 39 
Graphics, animation 199 

codes 188 

drawing patterns and 

figures 197-201 

line drawing 193-196, 

203-210 

processing 184-210 

random points 202 
Hamming code 266 
Hand assembling 86 
Hashing technique 401 
Hexadecimal 15 
Immediate value 28, 33 
INIT I/O call 256, 257 
Input buffer 145 
Input subroutines 144-147 
Input/output programming 

211-217 
Input/output, address 213 

cassette 221-227 

cassette music 227-233 

I/O mapped 212-214 

memory-mapped 215-217, 

242 

port addresses 214 

printer 217-221 
Instruction set 9-10 
Instruction times 270 
JR instructions 102 
Keyboard, bounce 136, 137 

scan 135-143 
KILL I/O call 260 
Listing 10, 60 
Listing file 59 
Loader, Disk Assembler 

71-74 
Location 17 
Lower case 186 
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Machine code, embedding in 

BASIC 99-111 

general 11, 14, 99 
Machine language 10, 13 
Macros, Disk Assembler 

62-65 
Memory allocation 78-81, 

87-89 
Mnemonic 10, 11, 40, 41 
Modulus operation 132 
Morse Code Generator 

Program 285-331 
Multiple-precision operations 

121, 134 
Multiply operations 123-126 
Object code 50 
Object file 77 
Op code 12, 38 
Operand 12 
Operation code 12 
Operators 48 

OPEN I/O call 251, 253, 254 
ORG pseudo-op 42 
Overflow 129, 130 
Pages, Disk Assembler 58 
Parameter list 98 
Patching 83-87, 93 
Periodicals, programming 

268 
Permutations 340-342 
Pixels 189-192 
Pointer 23 

POSN I/O call 261-263 
Preliminary specification 

268-271 
Printer input/output 217-221, 

326 
Program counter 18, 102 
Program design 271-278 
Program sections 54, 66 
Pseudo-ops 38, 42 
Pseudo-random number 

generation 131 



P/V flag 114, 115 

Random number generation 

130, 132, 321 
Ranges, of lines 55 
READ I/O call, 254-256 
Registers 23, 25 
Relative location 17 
Repeatability 50-52, 54, 61, 

93, 99-103 
Relocatable object file 59 
Research 266-268 
Restoring divide 127, 128 
Scaling 205, 206 
Scrolling, 150-152 
Searching 173-176 
SET/RESET 192 
Shift and add multiply, 124, 

125 
Signed multiplies and divides 

129 
Simulating text 287 
Single stepping 91 
Sorting 177-183 
Source code 11, 39 
Source file, creating on Disk 

Assembler 58 

general 14, 55 
Source line 59 
Stack operations 18-20, 28, 

78,79 
Subcommands, Disk 

Assembler editor 57 
Subroutine 11, 17, 111 
Subtract operations 116-122 
Successive addition multiply 

123 
Successive subtract divide 

127 
Symbol table 28, 46 
Symbolic code 10 
Syntax, assembler 39-41 

editor 38 

input subroutine 144 
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SYSTEM tapes 75-78 

T-BUG 78, 81-86 

Table size, automatic 168 

Tables, fixed-length entry, 
fixed length 159-161 
fixed-length entry, 
variable length 162, 163 
jump 165-169 
ordered 172 
scanning 169-171 
searching 173-176 
sorting 177-183 
variable-length entry, 
variable length 164, 165 
working with 159-183 



Testing, ,282 

Tic-Tac-Toe Program 333-410 

Tone generation, through 

cassette port 227-233, 291 
Trace 34 

TRSDOS I/O calls 251-263 
Two-buffer sort 177-180 
Unsigned multiplies and 

divides 129 
USR calls 94-97 
Word format 44, 45 
WRITE I/O call 257, 258 
Z flag 21 
Z-80 9 
Z-80 registers 23, 25 
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